{
  "data": [
    {
      "trace_id": "<string>",
      "name": "<string>",
      "status": "<string>",
      "duration": "<string>",
      "start_time": "2023-11-07T05:31:56Z",
      "total_spans": 123,
      "error_count": 123,
      "input": "<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"
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "total_pages": 0,
    "total_count": 0,
    "search_time_ms": 0
  }
}

Tracing

List Traces

Retrieve a paginated list of execution traces with optional filtering.

Traces provide observability into:

Agent execution flows
Model invocations and token usage
Tool calls and their results
Errors and performance bottlenecks

Filtering Options:

By run, session, user, or agent ID
By status (OK, ERROR)
By time range

Pagination:

Use page (1-indexed) and limit parameters
Response includes pagination metadata (total_pages, total_count, etc.)

Response Format: Returns summary information for each trace. Use GET /traces/{trace_id} for detailed hierarchy.

GET

traces

{
  "data": [
    {
      "trace_id": "<string>",
      "name": "<string>",
      "status": "<string>",
      "duration": "<string>",
      "start_time": "2023-11-07T05:31:56Z",
      "total_spans": 123,
      "error_count": 123,
      "input": "<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"
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "total_pages": 0,
    "total_count": 0,
    "search_time_ms": 0
  }
}

Authorizations

Authorization

string

header

required

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

Query Parameters

run_id

string | null

Filter by run ID

session_id

string | null

Filter by session ID

user_id

string | null

Filter by user ID

agent_id

string | null

Filter by agent ID

team_id

string | null

Filter by team ID

workflow_id

string | null

Filter by workflow ID

status

string | null

Filter by status (OK, ERROR)

start_time

string | null

Filter traces starting after this time (ISO 8601 format with timezone, e.g., '2025-11-19T10:00:00Z')

end_time

string | null

Filter traces ending before this time (ISO 8601 format with timezone, e.g., '2025-11-19T11:00:00Z')

page

integer

default:1

Page number (1-indexed)

Required range: x >= 1

limit

integer

default:20

Number of traces per page

Required range: 1 <= x <= 100

db_id

string | null

Database ID to query traces from

Response

List of traces retrieved successfully

data

TraceSummary · object[]

required

List of trace summaries

Show child attributes

data.trace_id

string

required

Unique trace identifier

data.name

string

required

Name of the root operation (e.g., Agent.run, Team.run)

data.status

string

required

Overall status (OK, ERROR, UNSET)

data.duration

string

required

Human-readable duration (e.g., "1.2s", "800ms")

data.start_time

string<date-time>

required

When the trace started (ISO 8601)

data.total_spans

integer

Number of spans in this trace

data.error_count

integer

Number of spans that errored

data.input

string | null

Input to the root operation

data.run_id

string | null

Associated run ID

data.session_id

string | null

Associated session ID

data.user_id

string | null

Associated user ID

data.agent_id

string | null

Associated agent ID

data.team_id

string | null

Associated team ID

data.workflow_id

string | null

Associated workflow ID

data.created_at

string<date-time>

When the trace record was created

Agno SDK Reference

AgentOS API Reference

List Traces

Authorizations

Query Parameters

Response