# Steps

## List Steps For Run

`client.runs.steps.list(stringrunID, StepListParamsquery?, RequestOptionsoptions?): ArrayPage<Step>`

**get** `/v1/runs/{run_id}/steps`

Get steps associated with a run with filtering options.

### Parameters

- `runID: string`

- `query: StepListParams`

  - `after?: string | null`

    Cursor for pagination (step ID). Returns results relative to this ID in the specified sort order. Expected format: 'step-<uuid4>'

  - `before?: string | null`

    Cursor for pagination (step ID). Returns results relative to this ID in the specified sort order. Expected format: 'step-<uuid4>'

  - `limit?: number | null`

    Maximum number of messages to return

  - `order?: "asc" | "desc"`

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

    - `"asc"`

    - `"desc"`

  - `order_by?: "created_at"`

    Field to sort by

    - `"created_at"`

### Returns

- `Step`

  - `id: string`

    The id of the step. Assigned by the database.

  - `agent_id?: string | null`

    The ID of the agent that performed the step.

  - `cache_write_tokens?: number | null`

    The number of input tokens written to cache (Anthropic only). None if not reported by provider.

  - `cached_input_tokens?: number | null`

    The number of input tokens served from cache. None if not reported by provider.

  - `completion_tokens?: number | null`

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

  - `completion_tokens_details?: Record<string, unknown> | null`

    Detailed completion token breakdown (e.g., reasoning_tokens).

  - `context_window_limit?: number | null`

    The context window limit configured for this step.

  - `error_data?: Record<string, unknown> | null`

    Error details including message, traceback, and additional context

  - `error_type?: string | null`

    The type/class of the error that occurred

  - `feedback?: "positive" | "negative" | null`

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

    - `"positive"`

    - `"negative"`

  - `messages?: Array<InternalMessage>`

    The messages generated during this step. Deprecated: use `GET /v1/steps/{step_id}/messages` endpoint instead

    - `id: string`

      The human-friendly ID of the Message

    - `role: MessageRole`

      The role of the participant.

      - `"assistant"`

      - `"user"`

      - `"tool"`

      - `"function"`

      - `"system"`

      - `"approval"`

      - `"summary"`

    - `agent_id?: string | null`

      The unique identifier of the agent.

    - `approval_request_id?: string | null`

      The id of the approval request if this message is associated with a tool call request.

    - `approvals?: Array<ApprovalReturn | LettaSchemasMessageToolReturnOutput> | null`

      The list of approvals for this message.

      - `ApprovalReturn`

        - `approve: boolean`

          Whether the tool has been approved

        - `tool_call_id: string`

          The ID of the tool call that corresponds to this approval

        - `reason?: string | null`

          An optional explanation for the provided approval status

        - `type?: "approval"`

          The message type to be created.

          - `"approval"`

      - `LettaSchemasMessageToolReturnOutput`

        - `status: "success" | "error"`

          The status of the tool call

          - `"success"`

          - `"error"`

        - `func_response?: string | Array<TextContent | ImageContent> | null`

          The function response - either a string or list of content parts (text/image)

          - `string`

          - `Array<TextContent | ImageContent>`

            - `TextContent`

              - `text: string`

                The text content of the message.

              - `signature?: string | null`

                Stores a unique identifier for any reasoning associated with this text content.

              - `type?: "text"`

                The type of the message.

                - `"text"`

            - `ImageContent`

              - `source: URLImage | Base64Image | LettaImage`

                The source of the image.

                - `URLImage`

                  - `url: string`

                    The URL of the image.

                  - `type?: "url"`

                    The source type for the image.

                    - `"url"`

                - `Base64Image`

                  - `data: string`

                    The base64 encoded image data.

                  - `media_type: string`

                    The media type for the image.

                  - `detail?: string | null`

                    What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

                  - `type?: "base64"`

                    The source type for the image.

                    - `"base64"`

                - `LettaImage`

                  - `file_id: string`

                    The unique identifier of the image file persisted in storage.

                  - `data?: string | null`

                    The base64 encoded image data.

                  - `detail?: string | null`

                    What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

                  - `media_type?: string | null`

                    The media type for the image.

                  - `type?: "letta"`

                    The source type for the image.

                    - `"letta"`

              - `type?: "image"`

                The type of the message.

                - `"image"`

        - `stderr?: Array<string> | null`

          Captured stderr from the tool invocation

        - `stdout?: Array<string> | null`

          Captured stdout (e.g. prints, logs) from the tool invocation

        - `tool_call_id?: unknown`

          The ID for the tool call

    - `approve?: boolean | null`

      Whether tool call is approved.

    - `batch_item_id?: string | null`

      The id of the LLMBatchItem that this message is associated with

    - `content?: Array<TextContent | ImageContent | ToolCallContent | 5 more> | null`

      The content of the message.

      - `TextContent`

      - `ImageContent`

      - `ToolCallContent`

        - `id: string`

          A unique identifier for this specific tool call instance.

        - `input: Record<string, unknown>`

          The parameters being passed to the tool, structured as a dictionary of parameter names to values.

        - `name: string`

          The name of the tool being called.

        - `signature?: string | null`

          Stores a unique identifier for any reasoning associated with this tool call.

        - `type?: "tool_call"`

          Indicates this content represents a tool call event.

          - `"tool_call"`

      - `ToolReturnContent`

        - `content: string`

          The content returned by the tool execution.

        - `is_error: boolean`

          Indicates whether the tool execution resulted in an error.

        - `tool_call_id: string`

          References the ID of the ToolCallContent that initiated this tool call.

        - `type?: "tool_return"`

          Indicates this content represents a tool return event.

          - `"tool_return"`

      - `ReasoningContent`

        Sent via the Anthropic Messages API

        - `is_native: boolean`

          Whether the reasoning content was generated by a reasoner model that processed this step.

        - `reasoning: string`

          The intermediate reasoning or thought process content.

        - `signature?: string | null`

          A unique identifier for this reasoning step.

        - `type?: "reasoning"`

          Indicates this is a reasoning/intermediate step.

          - `"reasoning"`

      - `RedactedReasoningContent`

        Sent via the Anthropic Messages API

        - `data: string`

          The redacted or filtered intermediate reasoning content.

        - `type?: "redacted_reasoning"`

          Indicates this is a redacted thinking step.

          - `"redacted_reasoning"`

      - `OmittedReasoningContent`

        A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)

        - `signature?: string | null`

          A unique identifier for this reasoning step.

        - `type?: "omitted_reasoning"`

          Indicates this is an omitted reasoning step.

          - `"omitted_reasoning"`

      - `SummarizedReasoningContent`

        The style of reasoning content returned by the OpenAI Responses API

        - `id: string`

          The unique identifier for this reasoning step.

        - `summary: Array<Summary>`

          Summaries of the reasoning content.

          - `index: number`

            The index of the summary part.

          - `text: string`

            The text of the summary part.

        - `encrypted_content?: string`

          The encrypted reasoning content.

        - `type?: "summarized_reasoning"`

          Indicates this is a summarized reasoning step.

          - `"summarized_reasoning"`

    - `conversation_id?: string | null`

      The conversation this message belongs to

    - `created_at?: string`

      The timestamp when the object was created.

    - `created_by_id?: string | null`

      The id of the user that made this object.

    - `denial_reason?: string | null`

      The reason the tool call request was denied.

    - `group_id?: string | null`

      The multi-agent group that the message was sent in

    - `is_err?: boolean | null`

      Whether this message is part of an error step. Used only for debugging purposes.

    - `last_updated_by_id?: string | null`

      The id of the user that made this object.

    - `model?: string | null`

      The model used to make the function call.

    - `name?: string | null`

      For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.

    - `otid?: string | null`

      The offline threading id associated with this message

    - `run_id?: string | null`

      The id of the run that this message was created in.

    - `sender_id?: string | null`

      The id of the sender of the message, can be an identity id or agent id

    - `step_id?: string | null`

      The id of the step that this message was created in.

    - `tool_call_id?: string | null`

      The ID of the tool call. Only applicable for role tool.

    - `tool_calls?: Array<ToolCall> | null`

      The list of tool calls requested. Only applicable for role assistant.

      - `id: string`

      - `function: Function`

        The function that the model called.

        - `arguments: string`

        - `name: string`

      - `type: "function"`

        - `"function"`

    - `tool_returns?: Array<ToolReturn> | null`

      Tool execution return information for prior tool calls

      - `status: "success" | "error"`

        The status of the tool call

        - `"success"`

        - `"error"`

      - `func_response?: string | Array<TextContent | ImageContent> | null`

        The function response - either a string or list of content parts (text/image)

        - `string`

        - `Array<TextContent | ImageContent>`

          - `TextContent`

          - `ImageContent`

      - `stderr?: Array<string> | null`

        Captured stderr from the tool invocation

      - `stdout?: Array<string> | null`

        Captured stdout (e.g. prints, logs) from the tool invocation

      - `tool_call_id?: unknown`

        The ID for the tool call

    - `updated_at?: string | null`

      The timestamp when the object was last updated.

  - `model?: string | null`

    The name of the model used for this step.

  - `model_endpoint?: string | null`

    The model endpoint url used for this step.

  - `model_handle?: string | null`

    The model handle (e.g., 'openai/gpt-4o-mini') used for this step.

  - `origin?: string | null`

    The surface that this agent step was initiated from.

  - `project_id?: string | null`

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

  - `prompt_tokens?: number | null`

    The number of tokens in the prompt during this step.

  - `prompt_tokens_details?: Record<string, unknown> | null`

    Detailed prompt token breakdown (e.g., cached_tokens, cache_read_tokens, cache_creation_tokens).

  - `provider_category?: string | null`

    The category of the provider used for this step.

  - `provider_id?: string | null`

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

  - `provider_name?: string | null`

    The name of the provider used for this step.

  - `reasoning_tokens?: number | null`

    The number of reasoning/thinking tokens generated. None if not reported by provider.

  - `request_id?: string | null`

    The API request log ID from cloud-api for correlating steps with API requests.

  - `run_id?: string | null`

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

  - `status?: "pending" | "success" | "failed" | "cancelled" | null`

    Status of a step execution

    - `"pending"`

    - `"success"`

    - `"failed"`

    - `"cancelled"`

  - `stop_reason?: StopReasonType | null`

    The stop reason associated with the step.

    - `"end_turn"`

    - `"error"`

    - `"llm_api_error"`

    - `"invalid_llm_response"`

    - `"invalid_tool_call"`

    - `"max_steps"`

    - `"max_tokens_exceeded"`

    - `"no_tool_call"`

    - `"tool_rule"`

    - `"cancelled"`

    - `"insufficient_credits"`

    - `"requires_approval"`

    - `"context_window_overflow_in_system_prompt"`

  - `tags?: Array<string>`

    Metadata tags.

  - `tid?: string | null`

    The unique identifier of the transaction that processed this step.

  - `total_tokens?: number | null`

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

  - `trace_id?: string | null`

    The trace id of the agent step.

### Example

```typescript
import Letta from '@letta-ai/letta-client';

const client = new Letta({
  apiKey: process.env['LETTA_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const step of client.runs.steps.list('run_id')) {
  console.log(step.id);
}
```

#### Response

```json
[
  {
    "id": "id",
    "agent_id": "agent_id",
    "cache_write_tokens": 0,
    "cached_input_tokens": 0,
    "completion_tokens": 0,
    "completion_tokens_details": {
      "foo": "bar"
    },
    "context_window_limit": 0,
    "error_data": {
      "foo": "bar"
    },
    "error_type": "error_type",
    "feedback": "positive",
    "messages": [
      {
        "id": "message-123e4567-e89b-12d3-a456-426614174000",
        "role": "assistant",
        "agent_id": "agent_id",
        "approval_request_id": "approval_request_id",
        "approvals": [
          {
            "approve": true,
            "tool_call_id": "tool_call_id",
            "reason": "reason",
            "type": "approval"
          }
        ],
        "approve": true,
        "batch_item_id": "batch_item_id",
        "content": [
          {
            "text": "text",
            "signature": "signature",
            "type": "text"
          }
        ],
        "conversation_id": "conversation_id",
        "created_at": "2019-12-27T18:11:19.117Z",
        "created_by_id": "created_by_id",
        "denial_reason": "denial_reason",
        "group_id": "group_id",
        "is_err": true,
        "last_updated_by_id": "last_updated_by_id",
        "model": "model",
        "name": "name",
        "otid": "otid",
        "run_id": "run_id",
        "sender_id": "sender_id",
        "step_id": "step_id",
        "tool_call_id": "tool_call_id",
        "tool_calls": [
          {
            "id": "id",
            "function": {
              "arguments": "arguments",
              "name": "name"
            },
            "type": "function"
          }
        ],
        "tool_returns": [
          {
            "status": "success",
            "func_response": "string",
            "stderr": [
              "string"
            ],
            "stdout": [
              "string"
            ],
            "tool_call_id": {}
          }
        ],
        "updated_at": "2019-12-27T18:11:19.117Z"
      }
    ],
    "model": "model",
    "model_endpoint": "model_endpoint",
    "model_handle": "model_handle",
    "origin": "origin",
    "project_id": "project_id",
    "prompt_tokens": 0,
    "prompt_tokens_details": {
      "foo": "bar"
    },
    "provider_category": "provider_category",
    "provider_id": "provider_id",
    "provider_name": "provider_name",
    "reasoning_tokens": 0,
    "request_id": "request_id",
    "run_id": "run_id",
    "status": "pending",
    "stop_reason": "end_turn",
    "tags": [
      "string"
    ],
    "tid": "tid",
    "total_tokens": 0,
    "trace_id": "trace_id"
  }
]
```