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.

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.

Fleet graph

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

{
  "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:

{
  "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:

{
  "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

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.

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

The source and target fields were renamed to from and to. The type field on edges was replaced by strength.

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

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

[
  {
    "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")

The response is capped at 20 traces, sorted from most recent to oldest.

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.

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

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

{
  "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

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

{
  "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.