Sign in

v36

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

List Run Steps

Get steps associated with a run with filtering options.

get/v1/runs/{run_id}/steps

Path parameters

run_idstring required

Query parameters

beforestring nullable

Cursor for pagination

Cursor for pagination

afterstring nullable

Cursor for pagination

Cursor for pagination

limitinteger nullable

Maximum number of messages to return

Maximum number of messages to return

order'asc' | 'desc'

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

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

order_by'created_at'

Field to sort by

Field to sort by

Response

Successful Response

idstring required

The id of the step. Assigned by the database.

originstring nullable

The surface that this agent step was initiated from.

provider_idstring nullable

The unique identifier of the provider that was configured for this step

run_idstring nullable

The unique identifier of the run that this step belongs to. Only included for async calls.

agent_idstring nullable

The ID of the agent that performed the step.

provider_namestring nullable

The name of the provider used for this step.

provider_categorystring nullable

The category of the provider used for this step.

modelstring nullable

The name of the model used for this step.

model_endpointstring nullable

The model endpoint url used for this step.

context_window_limitinteger nullable

The context window limit configured for this step.

completion_tokensinteger nullable

The number of tokens generated by the agent during this step.

prompt_tokensinteger nullable

The number of tokens in the prompt during this step.

total_tokensinteger nullable

The total number of tokens processed by the agent during this step.

completion_tokens_detailsobject nullable

Metadata for the agent.

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

Metadata tags.

tidstring nullable

The unique identifier of the transaction that processed this step.

trace_idstring nullable

The trace id of the agent step.

feedback'positive' | 'negative' nullable

The feedback for this step. Must be either 'positive' or 'negative'.

project_idstring nullable

The project that the agent that executed this step belongs to (cloud only).

error_typestring nullable

The type/class of the error that occurred

error_dataobject nullable

Error details including message, traceback, and additional context

status'pending' | 'success' | 'failed' | 'cancelled'

Status of a step execution

Example response

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