steps

List Steps

Changed on

List steps with optional pagination and date filters.

get/v1/steps/

Request

  • Base URL
    https://app.letta.com
  • URL
    https://app.letta.com/v1/steps/
  • Auth
    HTTP bearer

Query parameters

beforestring nullable

Return steps before this step ID

afterstring nullable

Return steps after this step ID

limitinteger nullable

Maximum number of steps 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

start_datestring nullable

Return steps after this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")

end_datestring nullable

Return steps before this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")

modelstring nullable

Filter by the name of the model used for the step

agent_idstring nullable

Filter by the ID of the agent that performed the step

trace_idsstring[] nullable

Filter by trace ids returned by the server

feedback'positive' | 'negative' nullable

Filter by feedback

has_feedbackboolean nullable

Filter by whether steps have feedback (true) or not (false)

tagsstring[] nullable

Filter by tags

project_idstring nullable

Filter by the project ID that is associated with the step (cloud only).

Headers

X-Projectstring nullable

Filter by project slug to associate with the group (cloud only).

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