## Retrieve Step

`client.steps.retrieve(stringstepID, RequestOptionsoptions?): Step`

**get** `/v1/steps/{step_id}`

Get a step by ID.

### Parameters

- `stepID: string`

  The ID of the step in the format 'step-<uuid4>'

### 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
});

const step = await client.steps.retrieve('step-123e4567-e89b-42d3-8456-426614174000');

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