Skip to content
Letta Letta Letta Docs
Sign up
API Reference
Steps
Messages

List Messages For Step

steps.messages.list(strstep_id, MessageListParams**kwargs) -> SyncArrayPage[MessageListResponse]
GET/v1/steps/{step_id}/messages

List messages for a given step.

ParametersExpand Collapse
step_id: str

The ID of the step in the format ‘step-’

minLength41
maxLength41
after: Optional[str]

Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: ‘message-’

minLength44
maxLength44
before: Optional[str]

Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: ‘message-’

minLength44
maxLength44
limit: Optional[int]

Maximum number of messages to return

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

Sort order for messages by creation time. ‘asc’ for oldest first, ‘desc’ for newest first

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

Sort by field

ReturnsExpand Collapse

A message generated by the system. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system

One of the following:
class SystemMessage: …

A message generated by the system. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system

id: str
content: str

The message content sent by the system

date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["system_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class UserMessage: …

A message sent by the user. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)

id: str
content: Union[List[LettaUserMessageContentUnion], str]

The message content sent by the user (can be a string or an array of multi-modal content parts)

One of the following:
List[LettaUserMessageContentUnion]
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.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

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.

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.

type: Optional[Literal["image"]]

The type of the message.

str
date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["user_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ReasoningMessage: …

Representation of an agent’s internal reasoning.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal[“reasoner_model”, “non_reasoner_model”]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step

id: str
date: datetime
reasoning: str
is_err: Optional[bool]
message_type: Optional[Literal["reasoning_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
signature: Optional[str]
source: Optional[Literal["reasoner_model", "non_reasoner_model"]]
One of the following:
"reasoner_model"
"non_reasoner_model"
step_id: Optional[str]
class HiddenReasoningMessage: …

Representation of an agent’s internal reasoning where reasoning content has been hidden from the response.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal[“redacted”, “omitted”]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent

id: str
date: datetime
state: Literal["redacted", "omitted"]
One of the following:
"redacted"
"omitted"
hidden_reasoning: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["hidden_reasoning_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ToolCallMessage: …

A message representing a request to call a tool (generated by the LLM to trigger tool execution).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call

id: str
date: datetime
Deprecatedtool_call: ToolCall
One of the following:
class ToolCall: …
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["tool_call_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
tool_calls: Optional[ToolCalls]
One of the following:
List[ToolCall]
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
class ToolReturnMessage: …

A message representing the return value of a tool call (generated by Letta executing the requested tool).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal[“success”, “error”]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support

id: str
date: datetime
Deprecatedstatus: Literal["success", "error"]
One of the following:
"success"
"error"
Deprecatedtool_call_id: str
Deprecatedtool_return: str
is_err: Optional[bool]
message_type: Optional[Literal["tool_return_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
Deprecatedstderr: Optional[List[str]]
Deprecatedstdout: Optional[List[str]]
step_id: Optional[str]
tool_returns: Optional[List[ToolReturn]]
status: Literal["success", "error"]
One of the following:
"success"
"error"
tool_call_id: str
tool_return: Union[List[ToolReturnUnionMember0], str]

The tool return value - either a string or list of content parts (text/image)

One of the following:
List[ToolReturnUnionMember0]
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.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

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.

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.

type: Optional[Literal["image"]]

The type of the message.

str
stderr: Optional[List[str]]
stdout: Optional[List[str]]
type: Optional[Literal["tool"]]

The message type to be created.

class AssistantMessage: …

A message sent by the LLM in response to user input. Used in the LLM context.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)

id: str
content: Union[List[LettaAssistantMessageContentUnion], str]

The message content sent by the agent (can be a string or an array of content parts)

One of the following:
List[LettaAssistantMessageContentUnion]
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.

str
date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["assistant_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ApprovalRequestMessage: …

A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call

id: str
date: datetime
Deprecatedtool_call: ToolCall

The tool call that has been requested by the llm to run

One of the following:
class ToolCall: …
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["approval_request_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
tool_calls: Optional[ToolCalls]

The tool calls that have been requested by the llm to run, which are pending approval

One of the following:
List[ToolCall]
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
class ApprovalResponseMessage: …

A message representing a response form the user indicating whether a tool has been approved to run.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status

id: str
date: datetime
Deprecatedapproval_request_id: Optional[str]

The message ID of the approval request

approvals: Optional[List[Approval]]

The list of approval responses

One of the following:
class ApprovalReturn: …
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.

class ToolReturn: …
status: Literal["success", "error"]
One of the following:
"success"
"error"
tool_call_id: str
tool_return: Union[List[ToolReturnUnionMember0], str]

The tool return value - either a string or list of content parts (text/image)

One of the following:
List[ToolReturnUnionMember0]
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.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

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.

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.

type: Optional[Literal["image"]]

The type of the message.

str
stderr: Optional[List[str]]
stdout: Optional[List[str]]
type: Optional[Literal["tool"]]

The message type to be created.

Deprecatedapprove: Optional[bool]

Whether the tool has been approved

is_err: Optional[bool]
message_type: Optional[Literal["approval_response_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

Deprecatedreason: Optional[str]

An optional explanation for the provided approval status

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class SummaryMessage: …

A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.

id: str
date: datetime
summary: str
compaction_stats: Optional[CompactionStats]

Statistics about a memory compaction operation.

context_window: int

The model’s context window size

messages_count_after: int

Number of messages after compaction

messages_count_before: int

Number of messages before compaction

trigger: str

What triggered the compaction (e.g., ‘context_window_exceeded’, ‘post_step_context_check’)

context_tokens_after: Optional[int]

Token count after compaction (message tokens only, does not include tool definitions)

context_tokens_before: Optional[int]

Token count before compaction (from LLM usage stats, includes full context sent to LLM)

is_err: Optional[bool]
message_type: Optional[Literal["summary_message"]]
name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class EventMessage: …

A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.

id: str
date: datetime
event_data: Dict[str, object]
event_type: Literal["compaction"]
is_err: Optional[bool]
message_type: Optional[Literal["event_message"]]
name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]

List Messages For Step

import os
from letta_client import Letta

client = Letta(
    api_key=os.environ.get("LETTA_API_KEY"),  # This is the default and can be omitted
)
page = client.steps.messages.list(
    step_id="step-123e4567-e89b-42d3-8456-426614174000",
)
page = page.items[0]
print(page)
[
  {
    "id": "id",
    "content": "content",
    "date": "2019-12-27T18:11:19.117Z",
    "is_err": true,
    "message_type": "system_message",
    "name": "name",
    "otid": "otid",
    "run_id": "run_id",
    "sender_id": "sender_id",
    "seq_id": 0,
    "step_id": "step_id"
  }
]
Returns Examples
[
  {
    "id": "id",
    "content": "content",
    "date": "2019-12-27T18:11:19.117Z",
    "is_err": true,
    "message_type": "system_message",
    "name": "name",
    "otid": "otid",
    "run_id": "run_id",
    "sender_id": "sender_id",
    "seq_id": 0,
    "step_id": "step_id"
  }
]