Skip to content
My Docs My Docs letta-sdk
  • Auto
  • Light
  • Dark
DiscordForumGitHubSign up
API Reference
Steps
View as Markdown
Copy Markdown
Open in Claude
Open in ChatGPT

List Steps

steps.list(StepListParams**kwargs) -> SyncArrayPage[Step]
get/v1/steps/

List steps with optional pagination and date filters.

ParametersExpand Collapse
after: Optional[str]

Return steps after this step ID

agent_id: Optional[str]

Filter by the ID of the agent that performed the step

before: Optional[str]

Return steps before this step ID

end_date: Optional[str]

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

feedback: Optional[Literal["positive", "negative"]]

Filter by feedback

Accepts one of the following:
"positive"
"negative"
has_feedback: Optional[bool]

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

limit: Optional[int]

Maximum number of steps to return

model: Optional[str]

Filter by the name of the model used for the step

order: Optional[Literal["asc", "desc"]]

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

Accepts one of the following:
"asc"
"desc"
order_by: Optional[Literal["created_at"]]

Field to sort by

Accepts one of the following:
"created_at"
project_id: Optional[str]

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

start_date: Optional[str]

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

tags: Optional[SequenceNotStr[str]]

Filter by tags

trace_ids: Optional[SequenceNotStr[str]]

Filter by trace ids returned by the server

ReturnsExpand Collapse
class Step: …
id: str

The id of the step. Assigned by the database.

agent_id: Optional[str]

The ID of the agent that performed the step.

completion_tokens: Optional[int]

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

completion_tokens_details: Optional[Dict[str, object]]

Metadata for the agent.

context_window_limit: Optional[int]

The context window limit configured for this step.

error_data: Optional[Dict[str, object]]

Error details including message, traceback, and additional context

error_type: Optional[str]

The type/class of the error that occurred

feedback: Optional[Literal["positive", "negative"]]

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

Accepts one of the following:
"positive"
"negative"
Deprecatedmessages: Optional[List[Message]]

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

id: str

The human-friendly ID of the Message

The role of the participant.

Accepts one of the following:
"assistant"
"user"
"tool"
"function"
"system"
"approval"
agent_id: Optional[str]

The unique identifier of the agent.

approval_request_id: Optional[str]

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

approvals: Optional[List[Approval]]

The list of approvals for this message.

Accepts one of the following:
class ApprovalApprovalReturn: …
approve: bool

Whether the tool has been approved

tool_call_id: str

The ID of the tool call that corresponds to this approval

reason: Optional[str]

An optional explanation for the provided approval status

type: Optional[Literal["approval"]]

The message type to be created.

Accepts one of the following:
"approval"
class ApprovalLettaSchemasMessageToolReturn: …
status: Literal["success", "error"]

The status of the tool call

Accepts one of the following:
"success"
"error"
func_response: Optional[str]

The function response string

stderr: Optional[List[str]]

Captured stderr from the tool invocation

stdout: Optional[List[str]]

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

tool_call_id: Optional[object]

The ID for the tool call

approve: Optional[bool]

Whether tool call is approved.

batch_item_id: Optional[str]

The id of the LLMBatchItem that this message is associated with

content: Optional[List[Content]]

The content of the message.

Accepts one of the following:
class TextContent: …
text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

Accepts one of the following:
"text"
class ImageContent: …
source: Source

The source of the image.

Accepts one of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

Accepts one of the following:
"url"
class SourceBase64Image: …
data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

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

type: Optional[Literal["base64"]]

The source type for the image.

Accepts one of the following:
"base64"
class SourceLettaImage: …
file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

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

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

Accepts one of the following:
"letta"
type: Optional[Literal["image"]]

The type of the message.

Accepts one of the following:
"image"
class ToolCallContent: …
id: str

A unique identifier for this specific tool call instance.

input: Dict[str, object]

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

name: str

The name of the tool being called.

signature: Optional[str]

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

type: Optional[Literal["tool_call"]]

Indicates this content represents a tool call event.

Accepts one of the following:
"tool_call"
class ToolReturnContent: …
content: str

The content returned by the tool execution.

is_error: bool

Indicates whether the tool execution resulted in an error.

tool_call_id: str

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

type: Optional[Literal["tool_return"]]

Indicates this content represents a tool return event.

Accepts one of the following:
"tool_return"
class ReasoningContent: …

Sent via the Anthropic Messages API

is_native: bool

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

reasoning: str

The intermediate reasoning or thought process content.

signature: Optional[str]

A unique identifier for this reasoning step.

type: Optional[Literal["reasoning"]]

Indicates this is a reasoning/intermediate step.

Accepts one of the following:
"reasoning"
class RedactedReasoningContent: …

Sent via the Anthropic Messages API

data: str

The redacted or filtered intermediate reasoning content.

type: Optional[Literal["redacted_reasoning"]]

Indicates this is a redacted thinking step.

Accepts one of the following:
"redacted_reasoning"
class 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: Optional[str]

A unique identifier for this reasoning step.

type: Optional[Literal["omitted_reasoning"]]

Indicates this is an omitted reasoning step.

Accepts one of the following:
"omitted_reasoning"
class ContentSummarizedReasoningContent: …

The style of reasoning content returned by the OpenAI Responses API

id: str

The unique identifier for this reasoning step.

summary: List[ContentSummarizedReasoningContentSummary]

Summaries of the reasoning content.

index: int

The index of the summary part.

text: str

The text of the summary part.

encrypted_content: Optional[str]

The encrypted reasoning content.

type: Optional[Literal["summarized_reasoning"]]

Indicates this is a summarized reasoning step.

Accepts one of the following:
"summarized_reasoning"
created_at: Optional[datetime]

The timestamp when the object was created.

formatdate-time
created_by_id: Optional[str]

The id of the user that made this object.

denial_reason: Optional[str]

The reason the tool call request was denied.

group_id: Optional[str]

The multi-agent group that the message was sent in

is_err: Optional[bool]

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

last_updated_by_id: Optional[str]

The id of the user that made this object.

model: Optional[str]

The model used to make the function call.

name: Optional[str]

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

otid: Optional[str]

The offline threading id associated with this message

run_id: Optional[str]

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

sender_id: Optional[str]

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

step_id: Optional[str]

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

tool_call_id: Optional[str]

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

tool_calls: Optional[List[ToolCall]]

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

id: str
function: ToolCallFunction
arguments: str
name: str
type: Literal["function"]
Accepts one of the following:
"function"
tool_returns: Optional[List[ToolReturn]]

Tool execution return information for prior tool calls

status: Literal["success", "error"]

The status of the tool call

Accepts one of the following:
"success"
"error"
func_response: Optional[str]

The function response string

stderr: Optional[List[str]]

Captured stderr from the tool invocation

stdout: Optional[List[str]]

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

tool_call_id: Optional[object]

The ID for the tool call

updated_at: Optional[datetime]

The timestamp when the object was last updated.

formatdate-time
model: Optional[str]

The name of the model used for this step.

model_endpoint: Optional[str]

The model endpoint url used for this step.

origin: Optional[str]

The surface that this agent step was initiated from.

project_id: Optional[str]

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

prompt_tokens: Optional[int]

The number of tokens in the prompt during this step.

provider_category: Optional[str]

The category of the provider used for this step.

provider_id: Optional[str]

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

provider_name: Optional[str]

The name of the provider used for this step.

run_id: Optional[str]

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

status: Optional[Literal["pending", "success", "failed", "cancelled"]]

Status of a step execution

Accepts one of the following:
"pending"
"success"
"failed"
"cancelled"
stop_reason: Optional[StopReasonType]

The stop reason associated with the step.

Accepts one of the following:
"end_turn"
"error"
"llm_api_error"
"invalid_llm_response"
"invalid_tool_call"
"max_steps"
"no_tool_call"
"tool_rule"
"cancelled"
"requires_approval"
tags: Optional[List[str]]

Metadata tags.

tid: Optional[str]

The unique identifier of the transaction that processed this step.

total_tokens: Optional[int]

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

trace_id: Optional[str]

The trace id of the agent step.

List Steps
  • HTTP
  • TypeScript
  • Python
from letta_client import Letta

client = Letta(
    api_key="My API Key",
)
page = client.steps.list()
page = page.items[0]
print(page.id)
[
  {
    "id": "id",
    "agent_id": "agent_id",
    "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"
          }
        ],
        "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": "func_response",
            "stderr": [
              "string"
            ],
            "stdout": [
              "string"
            ],
            "tool_call_id": {}
          }
        ],
        "updated_at": "2019-12-27T18:11:19.117Z"
      }
    ],
    "model": "model",
    "model_endpoint": "model_endpoint",
    "origin": "origin",
    "project_id": "project_id",
    "prompt_tokens": 0,
    "provider_category": "provider_category",
    "provider_id": "provider_id",
    "provider_name": "provider_name",
    "run_id": "run_id",
    "status": "pending",
    "stop_reason": "end_turn",
    "tags": [
      "string"
    ],
    "tid": "tid",
    "total_tokens": 0,
    "trace_id": "trace_id"
  }
]
Returns Examples
[
  {
    "id": "id",
    "agent_id": "agent_id",
    "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"
          }
        ],
        "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": "func_response",
            "stderr": [
              "string"
            ],
            "stdout": [
              "string"
            ],
            "tool_call_id": {}
          }
        ],
        "updated_at": "2019-12-27T18:11:19.117Z"
      }
    ],
    "model": "model",
    "model_endpoint": "model_endpoint",
    "origin": "origin",
    "project_id": "project_id",
    "prompt_tokens": 0,
    "provider_category": "provider_category",
    "provider_id": "provider_id",
    "provider_name": "provider_name",
    "run_id": "run_id",
    "status": "pending",
    "stop_reason": "end_turn",
    "tags": [
      "string"
    ],
    "tid": "tid",
    "total_tokens": 0,
    "trace_id": "trace_id"
  }
]