Agent Trace Viewer

The agent tracer records per-turn execution data: token counts, tool call durations, circuit breaker events, and final status. Traces are stored in the agent_traces table and queried via the /traces API. Use them to understand what happened inside a turn, diagnose slow or failed turns, and track cost over time.

What is recorded

Field	Description
`id`	Unique trace ID (one per turn)
`session_id`	Session the turn belongs to
`agent_id`	Agent that executed the turn
`duration_ms`	Total wall-clock time for the turn
`prompt_tokens`	Tokens sent to the model (includes context, tools, history)
`completion_tokens`	Tokens generated by the model
`tool_calls`	JSONB array — each entry has `toolName`, `durationMs`, `error`, `timestamp`
`circuit_breaker_events`	JSONB array — provider circuit breaker transitions during this turn
`final_status`	`completed` \| `timeout` \| `error`
`error_message`	Present when `final_status` is `error`

ℹTrace writes are fire-and-forget — a DB error writing a trace does not fail the agent turn. Traces are observability data, not operational data.

API

Endpoint	Description
`GET /traces`	List traces for the workspace, paginated. Filter by `agentId`, `limit` (max 200), `offset`.
`GET /traces/:id`	Full trace detail including `tool_calls` and `circuit_breaker_events` arrays.

Listing traces

bash

curl "http://localhost:3000/traces?agentId=researcher&limit=20" \
  -H "Authorization: Bearer $TOKEN"

json

{
  "traces": [
    {
      "id": "tr_01j...",
      "session_id": "ses_01j...",
      "agent_id": "researcher",
      "workspace_id": "ws_acme",
      "started_at": "2026-02-27T10:00:00Z",
      "finished_at": "2026-02-27T10:00:02.3Z",
      "duration_ms": 2300,
      "prompt_tokens": 1842,
      "completion_tokens": 512,
      "total_tokens": 2354,
      "final_status": "completed",
      "error_message": null,
      "tool_call_count": 4
    }
  ],
  "limit": 20,
  "offset": 0
}

The list endpoint returns a tool_call_count (derived from the JSONB array length) but not the full tool call array — fetch GET /traces/:id for the full breakdown.

Trace detail

json

{
  "trace": {
    "id": "tr_01j...",
    "tool_calls": [
      { "toolName": "web_search", "durationMs": 620, "error": null, "timestamp": 1740650400100 },
      { "toolName": "file_read",  "durationMs": 18,  "error": null, "timestamp": 1740650400720 }
    ],
    "circuit_breaker_events": [],
    "final_status": "completed"
  }
}

Workspace isolation

Traces are scoped to the authenticated workspace or user. You cannot read traces from another workspace. Requests without a matching workspace_id or uid return 404.

Common use cases

Diagnosing slow turns — sort by duration_ms DESC, then inspect the tool_calls array to find which tool dominated.
Tracking cost — sum total_tokens across traces grouped by agent_id for per-agent token cost analysis.
Debugging failures — filter by final_status=error and read error_message.
Circuit breaker history — check circuit_breaker_events on traces during a provider outage to see exactly when the circuit opened and closed.

See also: Agent Metrics for aggregate dashboards, Self-Healing for circuit breaker configuration.