Sign in

v36

latestOpenAPI 3.1.0raw.githubusercontent.com2025-10-091882241.2 MB
runs

List Runs

List all runs.

get/v1/runs/

Query parameters

agent_idstring nullable

The unique identifier of the agent associated with the run.

The unique identifier of the agent associated with the run.

agent_idsstring[] nullable

The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.

The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.

statusesstring[] nullable

Filter runs by status. Can specify multiple statuses.

Filter runs by status. Can specify multiple statuses.

backgroundboolean nullable

If True, filters for runs that were created in background mode.

If True, filters for runs that were created in background mode.

stop_reason'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'

Filter runs by stop reason.

beforestring nullable

Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order

Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order

afterstring nullable

Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order

Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order

limitinteger nullable

Maximum number of runs to return

Maximum number of runs to return

order'asc' | 'desc'

Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first

Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first

order_by'created_at'

Field to sort by

Field to sort by

activeboolean

Filter for active runs.

Filter for active runs.

ascendingboolean

Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field.

Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field.

Response

Successful Response

idstring

The human-friendly ID of the Run

status'created' | 'running' | 'completed' | 'failed' | 'cancelled'

Status of the run.

created_atstring date-time

The timestamp when the run was created.

completed_atstring date-time nullable

The timestamp when the run was completed.

agent_idstring required

The unique identifier of the agent associated with the run.

backgroundboolean nullable

Whether the run was created in background mode.

metadataobject nullable

Additional metadata for the run.

stop_reason'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'
callback_urlstring nullable

If set, POST to this URL when the run completes.

callback_sent_atstring date-time nullable

Timestamp when the callback was last attempted.

callback_status_codeinteger nullable

HTTP status code returned by the callback endpoint.

callback_errorstring nullable

Optional error message from attempting to POST the callback endpoint.

ttft_nsinteger nullable

Time to first token for a run in nanoseconds

total_duration_nsinteger nullable

Total run duration in nanoseconds

Example response

[
  {
    "id": "run-123e4567-e89b-12d3-a456-426614174000"
  }
]