Skip to content
Letta Letta Letta Docs
Sign up
API Reference

Messages

List All Messages
messages.list(MessageListParams**kwargs) -> MessageListResponse
GET/v1/messages/
Retrieve Message
messages.retrieve(strmessage_id) -> MessageRetrieveResponse
GET/v1/messages/{message_id}
Search All Messages
messages.search(MessageSearchParams**kwargs) -> MessageSearchResponse
POST/v1/messages/search
ModelsExpand Collapse
class MessageSearchRequest: …
query: str

Text query for full-text search

agent_id: Optional[str]

Filter messages by agent ID

conversation_id: Optional[str]

Filter messages by conversation ID

end_date: Optional[datetime]

Filter messages created on or before this date

formatdate-time
limit: Optional[int]

Maximum number of results to return

maximum100
minimum1
search_mode: Optional[Literal["vector", "fts", "hybrid"]]

Search mode to use

One of the following:
"vector"
"fts"
"hybrid"
start_date: Optional[datetime]

Filter messages created after this date

formatdate-time
class MessageSearchResult: …

Result from a message search operation with scoring details.

embedded_text: str

The embedded content (LLM-friendly)

The raw message object

id: str

The human-friendly ID of the Message

The role of the participant.

One of the following:
"assistant"
"user"
"tool"
"function"
"system"
"approval"
"summary"
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.

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 ApprovalLettaSchemasMessageToolReturnOutput: …
status: Literal["success", "error"]

The status of the tool call

One of the following:
"success"
"error"
func_response: Optional[Union[str, List[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1], null]]

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

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

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.

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.

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.

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.

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.

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.

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.

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.

conversation_id: Optional[str]

The conversation this message belongs to

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

The function that the model called.

arguments: str
name: str
type: Literal["function"]
tool_returns: Optional[List[ToolReturn]]

Tool execution return information for prior tool calls

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

The status of the tool call

One of the following:
"success"
"error"
func_response: Optional[Union[str, List[ToolReturnFuncResponseUnionMember1], null]]

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

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

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
rrf_score: float

Reciprocal Rank Fusion combined score

fts_rank: Optional[int]

Full-text search rank position if FTS was used

vector_rank: Optional[int]

Vector search rank position if vector search was used

List[Message]
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[Message]
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[MessageSearchResponseItem]
One of the following:
class MessageSearchResponseItemSystemMessageListResult: …

System message list result with agent context.

Shape is identical to UpdateSystemMessage but includes the owning agent_id and message id.

content: str

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

created_at: datetime

The time the message was created in ISO format.

formatdate-time
message_id: str

The unique identifier of the message.

agent_id: Optional[str]

The unique identifier of the agent that owns the message.

conversation_id: Optional[str]

The unique identifier of the conversation that the message belongs to.

message_type: Optional[Literal["system_message"]]
class MessageSearchResponseItemUserMessageListResult: …

User message list result with agent context.

Shape is identical to UpdateUserMessage but includes the owning agent_id and message id.

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
created_at: datetime

The time the message was created in ISO format.

formatdate-time
message_id: str

The unique identifier of the message.

agent_id: Optional[str]

The unique identifier of the agent that owns the message.

conversation_id: Optional[str]

The unique identifier of the conversation that the message belongs to.

message_type: Optional[Literal["user_message"]]
class MessageSearchResponseItemReasoningMessageListResult: …

Reasoning message list result with agent context.

Shape is identical to UpdateReasoningMessage but includes the owning agent_id and message id.

created_at: datetime

The time the message was created in ISO format.

formatdate-time
message_id: str

The unique identifier of the message.

reasoning: str
agent_id: Optional[str]

The unique identifier of the agent that owns the message.

conversation_id: Optional[str]

The unique identifier of the conversation that the message belongs to.

message_type: Optional[Literal["reasoning_message"]]
class MessageSearchResponseItemAssistantMessageListResult: …

Assistant message list result with agent context.

Shape is identical to UpdateAssistantMessage but includes the owning agent_id and message id.

content: Union[List[LettaAssistantMessageContentUnion], str]

The message content sent by the assistant (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
created_at: datetime

The time the message was created in ISO format.

formatdate-time
message_id: str

The unique identifier of the message.

agent_id: Optional[str]

The unique identifier of the agent that owns the message.

conversation_id: Optional[str]

The unique identifier of the conversation that the message belongs to.

message_type: Optional[Literal["assistant_message"]]