Sign in
runs

List Run Steps

Get messages associated with a run with filtering options.

Args: run_id: ID of the run before: A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. after: A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. limit: Maximum number of steps to return order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

Returns: A list of steps associated with the run.

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

orderstring

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

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"
      }
    ]
  }
]

Changes