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.

run_idstring nullable

Filter by run ID

session_idstring nullable

Filter by session ID

user_idstring nullable

Filter by user ID

agent_idstring nullable

Filter by agent ID

team_idstring nullable

Filter by team ID

workflow_idstring nullable

Filter by workflow ID

statusstring nullable

Filter by status (OK, ERROR)

start_timestring nullable

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_timestring nullable

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.

pageinteger

Page number (1-indexed)

limitinteger

Number of traces per page

db_idstring nullable

Database ID to query traces from

Response

List of traces retrieved successfully

v1

List Traces

Query parameters

Response