runs

List Run Steps

Changed on

Get steps associated with a run with filtering options.

get/v1/runs/{run_id}/steps

Request

  • Base URL
    https://app.letta.com
  • URL
    https://app.letta.com/v1/runs/{run_id}/steps
  • Auth
    HTTP bearer

Path parameters

run_idstring required

Query parameters

beforestring nullable

Cursor for pagination

afterstring nullable

Cursor for pagination

limitinteger nullable

Maximum number of messages to return

order'asc' | 'desc'

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

order_by'created_at'

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

Changes

  • 42a9cd544e13Revision changes
    • info

      added the optional property ////// to the response with the status

  • 1ba60b114a27Revision changes
    • info

      added the optional property ////// to the response with the status