> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-bridge-priority-values-1774820256.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mission control API

> Monitor your agent fleet with real-time graphs, execution traces, cost attribution, and booking data

# Mission control API

Mission control provides a real-time view of your agent fleet. Use these endpoints to visualize agent relationships, trace execution activity, attribute costs per agent, and track talent bookings.

<Note>All four mission control endpoints require bearer token (API key) authentication and accept a `userId` query parameter. The backend returns `401` for unauthenticated requests. The web proxy uses session authentication and resolves the user ID from the session before forwarding to these backend endpoints — the web proxy layer returns safe default responses (empty data with a `200` status) for unauthenticated requests instead of forwarding the `401`.</Note>

## Fleet graph

```http theme={null}
GET /api/mission-control/fleet/graph
```

Returns a constellation graph of your agent fleet as a set of nodes and edges. Each node represents an agent with a `role` and positional data for graph layout. Edges use `from`/`to` fields with a `strength` value indicating relationship weight.

### Authentication

Requires bearer token authentication.

### Query parameters

| Parameter | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| `userId`  | number | Yes      | The user ID to fetch the fleet graph for |

### Response

```json theme={null}
{
  "nodes": [
    {
      "id": "tempo-x402",
      "name": "tempo-x402",
      "role": "orchestrator",
      "status": "active",
      "x": 400,
      "y": 300,
      "load": 72,
      "memory": 58,
      "fitness": 85,
      "walletAddress": "0x1234...abcd",
      "children": 2,
      "endpoints": 3,
      "cycles": 1042,
      "regime": "explore",
      "freeEnergy": 0.34,
      "url": "https://tempo-x402-production.up.railway.app"
    },
    {
      "id": "a1b2c3d4",
      "name": "Clone-a1b2c3d4",
      "role": "worker",
      "status": "active",
      "x": 200,
      "y": 450,
      "load": 30,
      "memory": 20,
      "fitness": 40,
      "walletAddress": "0xabcd...1234"
    }
  ],
  "edges": [
    {
      "id": "e-tempo-x402-a1b2c3d4",
      "from": "tempo-x402",
      "to": "a1b2c3d4",
      "strength": 0.6
    }
  ],
  "timestamp": "2026-03-22T12:00:00.000Z",
  "source": "soul",
  "nodeCount": 1
}
```

When no souls are reachable, the response uses the fallback shape with minimal node data:

```json theme={null}
{
  "nodes": [
    {
      "id": "atlas",
      "name": "Atlas",
      "role": "orchestrator",
      "status": "offline",
      "x": 400,
      "y": 300,
      "load": 0,
      "memory": 0
    }
  ],
  "edges": [],
  "timestamp": "2026-03-22T12:00:00.000Z",
  "source": "fallback"
}
```

When the request is unauthenticated (no valid session), the web proxy returns a default response instead of forwarding the backend `401` error:

```json theme={null}
{
  "nodes": [
    {
      "id": "atlas",
      "name": "Atlas",
      "role": "orchestrator",
      "status": "offline",
      "x": 400,
      "y": 300,
      "load": 0,
      "memory": 0
    }
  ],
  "edges": [],
  "timestamp": "2026-03-22T12:00:00.000Z",
  "source": "unauthenticated"
}
```

### Node object

| Field           | Type   | Description                                                                                       |
| --------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `id`            | string | Unique agent identifier (designation or truncated instance ID for clones)                         |
| `name`          | string | Agent display name                                                                                |
| `role`          | string | Agent role. One of `orchestrator`, `specialist`, or `worker`                                      |
| `status`        | string | Current status. One of `active`, `idle`, `stale`, or `offline` (fallback only)                    |
| `x`             | number | Horizontal position for graph layout                                                              |
| `y`             | number | Vertical position for graph layout                                                                |
| `load`          | number | Current load percentage (0–100). Derived from active plan progress                                |
| `memory`        | number | Memory usage percentage (0–100). Derived from cortex experience count                             |
| `fitness`       | number | Fitness score (0–100). Only present on live nodes                                                 |
| `walletAddress` | string | On-chain wallet address of the agent. Present when available                                      |
| `children`      | number | Number of child (clone) instances. Only present on parent nodes                                   |
| `endpoints`     | number | Number of registered endpoints. Only present on parent nodes                                      |
| `cycles`        | number | Total cognitive cycles completed. Only present on parent nodes                                    |
| `regime`        | string | Current free energy regime (for example `"explore"` or `"exploit"`). Only present on parent nodes |
| `freeEnergy`    | number | Current free energy value. Only present on parent nodes                                           |
| `url`           | string | Soul instance URL. Only present on parent nodes                                                   |

<Note>The `type` field was renamed to `role` and now uses the values `orchestrator`, `specialist`, and `worker`. The `monitor` role is no longer returned by this endpoint.</Note>

### Edge object

| Field      | Type   | Description                         |
| ---------- | ------ | ----------------------------------- |
| `id`       | string | Unique edge identifier              |
| `from`     | string | Source agent ID                     |
| `to`       | string | Target agent ID                     |
| `strength` | number | Relationship weight between 0 and 1 |

<Note>The `source` and `target` fields were renamed to `from` and `to`. The `type` field on edges was replaced by `strength`.</Note>

### Response metadata

| Field       | Type   | Description                                                                                                                         |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp` | string | ISO 8601 timestamp of the response                                                                                                  |
| `source`    | string | Data source. `"soul"` for live data, `"fallback"` when no souls are reachable, `"unauthenticated"` when no valid session is present |
| `nodeCount` | number | Number of live soul nodes fetched. Only present when `source` is `"soul"`                                                           |

### Errors

| Code | Source  | Description                                    |
| ---- | ------- | ---------------------------------------------- |
| 401  | Backend | Unauthorized — missing or invalid bearer token |
| 500  | Backend | Internal server error                          |

The web proxy returns a `200` response with default empty data (see above) for unauthenticated requests instead of forwarding the backend `401`.

## Execution traces

```http theme={null}
GET /api/mission-control/fleet/traces
```

Returns up to 20 of the most recent execution traces for your agent fleet, sorted by recency. Each trace is returned as an `AgentTask`-shaped object with fields like `description`, `completedAt`, `tokensUsed`, and `costUSD`. Traces include active plan steps, recent thoughts, free energy component readings, and cycle status from live soul instances. Returns an empty array when no soul instances are reachable or when the request is unauthenticated.

### Authentication

Requires bearer token authentication.

### Query parameters

| Parameter | Type   | Required | Description                               |
| --------- | ------ | -------- | ----------------------------------------- |
| `userId`  | number | Yes      | The user ID to fetch execution traces for |

### Response

```json theme={null}
[
  {
    "id": "trace-plan-0",
    "status": "running",
    "description": "plan: reflect (2/5)",
    "startedAt": "2026-03-22T12:00:00.000Z",
    "completedAt": null,
    "tokensUsed": 0,
    "costUSD": 0,
    "model": "tempo-x402"
  },
  {
    "id": "trace-thought-0-0",
    "status": "completed",
    "description": "plan: next step is to consolidate memory entries",
    "startedAt": "2026-03-22T11:59:56.000Z",
    "completedAt": "2026-03-22T11:59:56.285Z",
    "tokensUsed": 542,
    "costUSD": 0,
    "model": "tempo-x402"
  },
  {
    "id": "trace-fe-0-0",
    "status": "completed",
    "description": "cortex: surprise=0.12, contribution=0.04",
    "startedAt": "2026-03-22T11:59:50.000Z",
    "completedAt": "2026-03-22T11:59:50.001Z",
    "tokensUsed": 0,
    "costUSD": 0,
    "model": "tempo-x402"
  },
  {
    "id": "trace-cycles-0",
    "status": "idle",
    "description": "cycle 1042 complete — mode: active, regime: explore",
    "startedAt": "2026-03-22T11:59:45.000Z",
    "completedAt": null,
    "tokensUsed": 0,
    "costUSD": 0,
    "model": "tempo-x402"
  }
]
```

### Trace object (AgentTask shape)

| Field         | Type           | Description                                                                                                                             |
| ------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | string         | Unique trace identifier                                                                                                                 |
| `status`      | string         | Execution result. One of `completed`, `running`, or `idle`. Raw `success` status is mapped to `completed`                               |
| `description` | string         | Description of the task executed                                                                                                        |
| `startedAt`   | string         | ISO 8601 timestamp when the task started                                                                                                |
| `completedAt` | string \| null | ISO 8601 timestamp when the task finished. Computed from the original duration for timed traces. `null` for ongoing or non-timed traces |
| `tokensUsed`  | number         | Token count for inference-type traces. `0` for other trace types                                                                        |
| `costUSD`     | number         | Cost in USD attributed to this trace. Currently always `0`                                                                              |
| `model`       | string         | Soul designation that produced the trace (for example `"tempo-x402"`)                                                                   |

<Note>The response is capped at 20 traces, sorted from most recent to oldest.</Note>

<Note>The previous raw trace fields (`type`, `label`, `agent`, `duration`, `tokens`) have been replaced by the `AgentTask` shape (`description`, `completedAt`, `tokensUsed`, `costUSD`, `model`). The `status` value `success` is now returned as `completed`.</Note>

### Errors

| Code | Source  | Description                                    |
| ---- | ------- | ---------------------------------------------- |
| 401  | Backend | Unauthorized — missing or invalid bearer token |
| 500  | Backend | Internal server error                          |

The web proxy returns a `200` response with an empty array `[]` for unauthenticated requests instead of forwarding the backend `401`.

## Cost attribution

```http theme={null}
GET /api/mission-control/fleet/costs
```

Returns a cost breakdown for your agent fleet. Requires bearer token authentication. The web proxy uses session authentication and resolves the user ID from the session before forwarding to this backend endpoint. Returns a default empty response for unauthenticated requests.

### Authentication

Requires bearer token authentication.

### Query parameters

| Parameter | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `userId`  | number | Yes      | The user ID to fetch cost data for |

### Response

```json theme={null}
{
  "costs": [],
  "totalSpend": 0,
  "managedAiCost": 0,
  "coordinationRevenue": 0
}
```

### Response fields

| Field                 | Type   | Description                                                                                     |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `costs`               | array  | List of cost line items. Currently returns an empty array while real data wiring is in progress |
| `totalSpend`          | number | Total spend across the fleet                                                                    |
| `managedAiCost`       | number | AI model usage cost                                                                             |
| `coordinationRevenue` | number | Revenue from agent coordination                                                                 |

### Errors

| Code | Source  | Description                                    |
| ---- | ------- | ---------------------------------------------- |
| 401  | Backend | Unauthorized — missing or invalid bearer token |
| 500  | Backend | Internal server error                          |

The web proxy returns a `200` response with `{ costs: [] }` for unauthenticated requests instead of forwarding the backend `401`.

## Talent bookings

```http theme={null}
GET /api/mission-control/fleet/bookings
```

Returns active booking requests for your agent fleet. Requires bearer token authentication. The web proxy uses session authentication and resolves the user ID from the session before forwarding to this backend endpoint. Returns a default empty response for unauthenticated requests.

### Authentication

Requires bearer token authentication.

### Query parameters

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `userId`  | number | Yes      | The user ID to fetch booking data for |

### Response

```json theme={null}
{
  "bookings": []
}
```

### Response fields

| Field      | Type  | Description                                                                                     |
| ---------- | ----- | ----------------------------------------------------------------------------------------------- |
| `bookings` | array | List of booking objects. Currently returns an empty array while real data wiring is in progress |

### Errors

| Code | Source  | Description                                    |
| ---- | ------- | ---------------------------------------------- |
| 401  | Backend | Unauthorized — missing or invalid bearer token |
| 500  | Backend | Internal server error                          |

The web proxy returns a `200` response with `{ bookings: [] }` for unauthenticated requests instead of forwarding the backend `401`.