Get Trace Or Span Detail

Trace storage

Configure AgentOS tracing with a registered trace-capable database and an exporter that writes to it. An ordinary model run alone does not guarantee stored traces. Select db_id when multiple databases are registered. These trace endpoints select storage by db_id only; they do not accept a table selector.

Trace ownership follows the effective user scope: JWT user isolation is opt-in, while non-admin service-account PAT callers self-scope. Configured authorization also requires trace read access. Use IDs returned by trace listing for detail requests.

Trace tree or one span

Without span_id, the response is a trace detail whose tree[].spans contains child spans. The generated children example is stale. Every node has id, name, type, duration, start_time, end_time and status; times are ISO 8601 strings.

With span_id, this endpoint returns the selected span node. That span must belong to the path's trace. An optional run_id helps lookup; it does not authorize pairing an arbitrary trace ID with a span from another trace.

GET/traces/{trace_id}

Retrieve detailed trace information with hierarchical span tree, or a specific span within the trace.

Without span_id parameter: Returns the full trace with hierarchical span tree:

  • Trace metadata (ID, status, duration, context)
  • Hierarchical tree of all spans
  • Each span includes timing, status, and type-specific metadata

With span_id parameter: Returns details for a specific span within the trace:

  • Span metadata (ID, name, type, timing)
  • Status and error information
  • Type-specific attributes (model, tokens, tool params, etc.)

Span Hierarchy (full trace): The tree field contains root spans, each with potential children. This recursive structure represents the execution flow:

Agent.run (root)  ├─ LLM.invoke  ├─ Tool.execute  │   └─ LLM.invoke (nested)  └─ LLM.invoke

Span Types:

  • AGENT: Agent execution with input/output
  • LLM: Model invocations with tokens and prompts
  • TOOL: Tool calls with parameters and results

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

trace_id*Trace Id

Query Parameters

span_id?|

Optional: Span ID to retrieve specific span

run_id?|

Optional: Run ID to retrieve trace for

db_id?|

Database ID to query trace from

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request GET 'https://example.com/traces/string'

{  "trace_id": "a1b2c3d4",  "name": "Stock_Price_Agent.run",  "status": "OK",  "duration": "1.2s",  "start_time": "2025-11-19T10:30:00.000000+00:00",  "end_time": "2025-11-19T10:30:01.200000+00:00",  "total_spans": 4,  "error_count": 0,  "input": "What is Tesla stock price?",  "output": "The current price of Tesla (TSLA) is $245.67.",  "run_id": "run123",  "session_id": "session456",  "user_id": "user789",  "agent_id": "stock_agent",  "created_at": "2025-11-19T10:30:00+00:00",  "tree": [    {      "id": "span1",      "name": "Stock_Price_Agent.run",      "type": "AGENT",      "duration": "1.2s",      "status": "OK",      "spans": []    }  ]}