---
title: "List Steps"
method: GET
path: "/v1/steps/"
tags: ["steps"]
---

# List Steps

`GET /v1/steps/`

List steps with optional pagination and date filters.

## Query parameters

- `before` string, nullable — Return steps before this step ID
- `after` string, nullable — Return steps after this step ID
- `limit` integer, 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_date` string, nullable — Return steps after this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")
- `end_date` string, nullable — Return steps before this ISO datetime (e.g. "2025-01-29T15:01:19-08:00")
- `model` string, nullable — Filter by the name of the model used for the step
- `agent_id` string, nullable — Filter by the ID of the agent that performed the step
- `trace_ids` string[], nullable — Filter by trace ids returned by the server
- `feedback` 'positive' | 'negative', nullable — Filter by feedback
- `has_feedback` boolean, nullable — Filter by whether steps have feedback (true) or not (false)
- `tags` string[], nullable — Filter by tags
- `project_id` string, nullable — Filter by the project ID that is associated with the step (cloud only).

## Headers

- `X-Project` string, nullable — Filter by project slug to associate with the group (cloud only).

## Response `200`

Successful Response

- Step[]
  - `id` string, required — The id of the step. Assigned by the database.
  - `origin` string, nullable — The surface that this agent step was initiated from.
  - `provider_id` string, nullable — The unique identifier of the provider that was configured for this step
  - `run_id` string, nullable — The unique identifier of the run that this step belongs to. Only included for async calls.
  - `agent_id` string, nullable — The ID of the agent that performed the step.
  - `provider_name` string, nullable — The name of the provider used for this step.
  - `provider_category` string, nullable — The category of the provider used for this step.
  - `model` string, nullable — The name of the model used for this step.
  - `model_endpoint` string, nullable — The model endpoint url used for this step.
  - `context_window_limit` integer, nullable — The context window limit configured for this step.
  - `completion_tokens` integer, nullable — The number of tokens generated by the agent during this step.
  - `prompt_tokens` integer, nullable — The number of tokens in the prompt during this step.
  - `total_tokens` integer, nullable — The total number of tokens processed by the agent during this step.
  - `completion_tokens_details` object, 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'
  - `tags` string[] — Metadata tags.
  - `tid` string, nullable — The unique identifier of the transaction that processed this step.
  - `trace_id` string, nullable — The trace id of the agent step.
  - `messages` Message[] — The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead
    - `created_by_id` string, nullable — The id of the user that made this object.
    - `last_updated_by_id` string, nullable — The id of the user that made this object.
    - `created_at` string, date-time — The timestamp when the object was created.
    - `updated_at` string, date-time, nullable — The timestamp when the object was last updated.
    - `id` string — The human-friendly ID of the Message
    - `agent_id` string, nullable — The unique identifier of the agent.
    - `model` string, nullable — The model used to make the function call.
    - `role` 'assistant' | 'user' | 'tool' | 'function' | 'system' | 'approval', required
    - `content` union[], nullable — The content of the message.
      - union
        - TextContent
          - `type` 'text' — The type of the message.
          - `text` string, required — The text content of the message.
          - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this text content.
        - ImageContent
          - `type` 'image' — The type of the message.
          - `source` union, required — The source of the image.
            - UrlImage
              - …
            - Base64Image
              - …
            - LettaImage
              - …
        - ToolCallContent
          - `type` 'tool_call' — Indicates this content represents a tool call event.
          - `id` string, required — A unique identifier for this specific tool call instance.
          - `name` string, required — The name of the tool being called.
          - `input` object, required — The parameters being passed to the tool, structured as a dictionary of parameter names to values.
          - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this tool call.
        - ToolReturnContent
          - `type` 'tool_return' — Indicates this content represents a tool return event.
          - `tool_call_id` string, required — References the ID of the ToolCallContent that initiated this tool call.
          - `content` string, required — The content returned by the tool execution.
          - `is_error` boolean, required — Indicates whether the tool execution resulted in an error.
        - ReasoningContent — Sent via the Anthropic Messages API
          - `type` 'reasoning' — Indicates this is a reasoning/intermediate step.
          - `is_native` boolean, required — Whether the reasoning content was generated by a reasoner model that processed this step.
          - `reasoning` string, required — The intermediate reasoning or thought process content.
          - `signature` string, nullable — A unique identifier for this reasoning step.
        - RedactedReasoningContent — Sent via the Anthropic Messages API
          - `type` 'redacted_reasoning' — Indicates this is a redacted thinking step.
          - `data` string, required — The redacted or filtered intermediate reasoning content.
        - OmittedReasoningContent — A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)
          - `type` 'omitted_reasoning' — Indicates this is an omitted reasoning step.
          - `signature` string, nullable — A unique identifier for this reasoning step.
        - SummarizedReasoningContent — The style of reasoning content returned by the OpenAI Responses API
          - `type` 'summarized_reasoning' — Indicates this is a summarized reasoning step.
          - `id` string, required — The unique identifier for this reasoning step.
          - `summary` SummarizedReasoningContentPart[], required — Summaries of the reasoning content.
            - `index` integer, required — The index of the summary part.
            - `text` string, required — The text of the summary part.
          - `encrypted_content` string — The encrypted reasoning content.
    - `name` string, nullable — For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.
    - `tool_calls` ChatCompletionMessageFunctionToolCall[], nullable — The list of tool calls requested. Only applicable for role assistant.
      - `id` string, required
      - `function` Function, required
        - `arguments` string, required
        - `name` string, required
      - `type` 'function', required
    - `tool_call_id` string, nullable — The ID of the tool call. Only applicable for role tool.
    - `step_id` string, nullable — The id of the step that this message was created in.
    - `run_id` string, nullable — The id of the run that this message was created in.
    - `otid` string, nullable — The offline threading id associated with this message
    - `tool_returns` LettaSchemasMessageToolReturn[], nullable — Tool execution return information for prior tool calls
      - `tool_call_id` unknown
      - `status` 'success' | 'error', required — The status of the tool call
      - `stdout` string[], nullable — Captured stdout (e.g. prints, logs) from the tool invocation
      - `stderr` string[], nullable — Captured stderr from the tool invocation
      - `func_response` string, nullable — The function response string
    - `group_id` string, nullable — The multi-agent group that the message was sent in
    - `sender_id` string, nullable — The id of the sender of the message, can be an identity id or agent id
    - `batch_item_id` string, nullable — The id of the LLMBatchItem that this message is associated with
    - `is_err` boolean, nullable — Whether this message is part of an error step. Used only for debugging purposes.
    - `approval_request_id` string, nullable — The id of the approval request if this message is associated with a tool call request.
    - `approve` boolean, nullable — Whether tool call is approved.
    - `denial_reason` string, nullable — The reason the tool call request was denied.
  - `feedback` 'positive' | 'negative', nullable — The feedback for this step. Must be either 'positive' or 'negative'.
  - `project_id` string, nullable — The project that the agent that executed this step belongs to (cloud only).
  - `error_type` string, nullable — The type/class of the error that occurred
  - `error_data` object, nullable — Error details including message, traceback, and additional context
  - `status` 'pending' | 'success' | 'failed' | 'cancelled' — Status of a step execution

## Other responses

- `422` — Validation Error

## Changes

- **2025-10-07** `42a9cd544e13` — 1 info
  - added the optional property `items/messages/items/tool_returns/anyOf[subschema #1]/items/func_response` to the response with the `200` status
- **2025-10-07** `1ba60b114a27` — 1 info
  - added the optional property `items/messages/items/tool_returns/anyOf[subschema #1]/items/tool_call_id` to the response with the `200` status
- **2025-10-03** `f0554a0bf8b2` — 3 info
  - added the optional property `items/messages/items/content/anyOf[subschema #1]/items/oneOf[subschema #1: TextContent]/signature` to the response with the `200` status
  - added the optional property `items/messages/items/content/anyOf[subschema #1]/items/oneOf[subschema #3: ToolCallContent]/signature` to the response with the `200` status
  - added the optional property `items/messages/items/content/anyOf[subschema #1]/items/oneOf[subschema #7: OmittedReasoningContent]/signature` to the response with the `200` status
- **2025-09-29** `ac8e1eb68404` — 1 warning, 2 info
  - removed the optional property `items/job_id` from the response with the `200` status
  - added the optional property `items/messages/items/run_id` to the response with the `200` status
  - added the optional property `items/run_id` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/yu-code666/apis/letta-api/changes/v1/steps/get.md)

---

[API](https://skmtc.dev/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.dev/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yu-code666/letta-api/revisions/6cec99480c13/schema)