Traces

List Traces

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.

The response has data containing trace summaries and pagination meta. A summary includes both start_time and end_time, along with trace_id, name, status, formatted duration, total_spans and error_count. Optional run/session/component identity depends on the stored trace.

The generated sample omits end_time; use the current schema for field handling. Fetch trace detail for the span tree.

GET/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.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

run_id?|

Filter by run ID

session_id?|

Filter by session ID

user_id?|

Filter by user ID

agent_id?|

Filter by agent ID

team_id?|

Filter by team ID

workflow_id?|

Filter by workflow ID

status?|

Filter by status (OK, ERROR)

start_time?|

Filter traces starting after this time (ISO 8601 format with timezone, e.g., '2025-11-19T10:00:00Z' or '2025-11-19T15:30:00+05:30'). Times are converted to UTC for comparison.

end_time?|

Filter traces ending before this time (ISO 8601 format with timezone, e.g., '2025-11-19T11:00:00Z' or '2025-11-19T16:30:00+05:30'). Times are converted to UTC for comparison.

page?Page

Page number (1-indexed)

Range0 <= value
Default1
limit?Limit

Number of traces per page

Range1 <= value
Default20
db_id?|

Database ID to query traces from

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request GET 'https://example.com/traces'
{  "data": [    {      "trace_id": "a1b2c3d4",      "name": "Stock_Price_Agent.run",      "status": "OK",      "duration": "1.2s",      "start_time": "2025-11-19T10:30:00.000000+00:00",      "total_spans": 4,      "error_count": 0,      "input": "What is the stock price of NVDA?",      "run_id": "run123",      "session_id": "session456",      "user_id": "user789",      "agent_id": "agent_stock",      "created_at": "2025-11-19T10:30:00+00:00"    }  ],  "meta": {    "page": 1,    "limit": 20,    "total_pages": 5,    "total_count": 95  }}

Get Config

Previous Page

Get Trace Filter Schema

Next Page