{
  "trace_id": "<string>",
  "name": "<string>",
  "status": "<string>",
  "duration": "<string>",
  "start_time": "2023-11-07T05:31:56Z",
  "end_time": "2023-11-07T05:31:56Z",
  "tree": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "duration": "<string>",
      "status": "<string>",
      "input": "<string>",
      "output": "<string>",
      "error": "<string>",
      "metadata": {},
      "spans": [
        "<unknown>"
      ]
    }
  ],
  "total_spans": 123,
  "error_count": 123,
  "input": "<string>",
  "output": "<string>",
  "error": "<string>",
  "run_id": "<string>",
  "session_id": "<string>",
  "user_id": "<string>",
  "agent_id": "<string>",
  "team_id": "<string>",
  "workflow_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z"
}

Tracing

Get Trace Detail

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: The tree field contains root spans, each with potential children. This recursive structure represents the execution flow.

Span Types:

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

GET

traces

{trace_id}

{
  "trace_id": "<string>",
  "name": "<string>",
  "status": "<string>",
  "duration": "<string>",
  "start_time": "2023-11-07T05:31:56Z",
  "end_time": "2023-11-07T05:31:56Z",
  "tree": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "duration": "<string>",
      "status": "<string>",
      "input": "<string>",
      "output": "<string>",
      "error": "<string>",
      "metadata": {},
      "spans": [
        "<unknown>"
      ]
    }
  ],
  "total_spans": 123,
  "error_count": 123,
  "input": "<string>",
  "output": "<string>",
  "error": "<string>",
  "run_id": "<string>",
  "session_id": "<string>",
  "user_id": "<string>",
  "agent_id": "<string>",
  "team_id": "<string>",
  "workflow_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

trace_id

string

required

Trace ID to retrieve

Query Parameters

span_id

string | null

Optional span ID to retrieve specific span

run_id

string | null

Optional run ID to retrieve trace for

db_id

string | null

Database ID to query trace from

Response

Trace or span detail retrieved successfully

trace_id

string

required

Unique trace identifier

name

string

required

Name of the root operation

status

string

required

Overall status (OK, ERROR, UNSET)

duration

string

required

Human-readable duration

start_time

string<date-time>

required

When the trace started

end_time

string<date-time>

required

When the trace completed

tree

TraceNode · object[]

required

Hierarchical span tree

Show child attributes

tree.id

string

required

Span ID

tree.name

string

required

Operation name

tree.type

string

required

Span type (AGENT, LLM, TOOL, etc.)

tree.duration

string

required

Human-readable duration

tree.status

string

required

Span status (OK, ERROR, UNSET)

tree.input

string | null

Input to the operation

tree.output

string | null

Output from the operation

tree.error

string | null

Error message if status is ERROR

tree.metadata

Metadata · object

Type-specific metadata (model, tokens, tool params, etc.)

tree.spans

any[] | null

Child spans (recursive hierarchy)

total_spans

integer

Number of spans in this trace

error_count

integer

Number of spans that errored

input

string | null

Input to the root operation

output

string | null

Output from the root operation

error

string | null

Error message if status is ERROR

run_id

string | null

Associated run ID

session_id

string | null

Associated session ID

user_id

string | null

Associated user ID

agent_id

string | null

Associated agent ID

team_id

string | null

Associated team ID

workflow_id

string | null

Associated workflow ID

created_at

string<date-time>

When the trace record was created

List Traces Get Trace Statistics by Session

⌘I

Agno SDK Reference

AgentOS API Reference

Get Trace Detail

Authorizations

Path Parameters

Query Parameters

Response