Messages
List All Messages
Retrieve Message
Search All Messages
ModelsExpand Collapse
MessageSearchResult object { embedded_text, message, rrf_score, 2 more }
Result from a message search operation with scoring details.
The raw message object
approval_request_id: optional string
The id of the approval request if this message is associated with a tool call request.
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or object { status, func_response, stderr, 2 more }
The list of approvals for this message.
LettaSchemasMessageToolReturnOutput object { status, func_response, stderr, 2 more }
func_response: optional string or array of TextContent { text, signature, type } or ImageContent { source, type }
The function response - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
content: optional array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more
The content of the message.
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ToolCallContent object { id, input, name, 2 more }
ReasoningContent object { is_native, reasoning, signature, type }
is_err: optional boolean
Whether this message is part of an error step. Used only for debugging purposes.
name: optional string
For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.
tool_returns: optional array of object { status, func_response, stderr, 2 more }
Tool execution return information for prior tool calls
func_response: optional string or array of TextContent { text, signature, type } or ImageContent { source, type }
The function response - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
SystemMessage object { id, content, date, 8 more }
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
UserMessage object { id, content, date, 8 more }
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)
The message content sent by the user (can be a string or an array of multi-modal content parts)
array of LettaUserMessageContentUnion
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ReasoningMessage object { id, date, reasoning, 10 more }
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
otid: optional string
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.
HiddenReasoningMessage object { id, date, state, 9 more }
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
ToolCallMessage object { id, date, tool_call, 9 more }
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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
otid: optional string
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.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
array of ToolCall { arguments, name, tool_call_id }
ToolReturnMessage object { id, date, status, 13 more }
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
otid: optional string
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.
tool_return: array of TextContent { text, signature, type } or ImageContent { source, type } or string
The tool return value - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
AssistantMessage object { id, content, date, 8 more }
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)
The message content sent by the agent (can be a string or an array of content parts)
array of LettaAssistantMessageContentUnion { text, signature, type }
ApprovalRequestMessage object { id, date, tool_call, 9 more }
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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool call that has been requested by the llm to run
otid: optional string
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.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool calls that have been requested by the llm to run, which are pending approval
array of ToolCall { arguments, name, tool_call_id }
ApprovalResponseMessage object { id, date, approval_request_id, 11 more }
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
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ToolReturn object { status, tool_call_id, tool_return, 3 more }
tool_return: array of TextContent { text, signature, type } or ImageContent { source, type } or string
The tool return value - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
SummaryMessage object { id, date, summary, 9 more }
A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.
compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }
EventMessage object { id, date, event_data, 9 more }
A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.
SystemMessage object { id, content, date, 8 more }
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
UserMessage object { id, content, date, 8 more }
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)
The message content sent by the user (can be a string or an array of multi-modal content parts)
array of LettaUserMessageContentUnion
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ReasoningMessage object { id, date, reasoning, 10 more }
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
otid: optional string
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.
HiddenReasoningMessage object { id, date, state, 9 more }
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
ToolCallMessage object { id, date, tool_call, 9 more }
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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
otid: optional string
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.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
array of ToolCall { arguments, name, tool_call_id }
ToolReturnMessage object { id, date, status, 13 more }
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
otid: optional string
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.
tool_return: array of TextContent { text, signature, type } or ImageContent { source, type } or string
The tool return value - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
AssistantMessage object { id, content, date, 8 more }
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)
The message content sent by the agent (can be a string or an array of content parts)
array of LettaAssistantMessageContentUnion { text, signature, type }
ApprovalRequestMessage object { id, date, tool_call, 9 more }
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
Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool call that has been requested by the llm to run
otid: optional string
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.
tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }
The tool calls that have been requested by the llm to run, which are pending approval
array of ToolCall { arguments, name, tool_call_id }
ApprovalResponseMessage object { id, date, approval_request_id, 11 more }
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
approvals: optional array of ApprovalReturn { approve, tool_call_id, reason, type } or ToolReturn { status, tool_call_id, tool_return, 3 more }
The list of approval responses
ToolReturn object { status, tool_call_id, tool_return, 3 more }
tool_return: array of TextContent { text, signature, type } or ImageContent { source, type } or string
The tool return value - either a string or list of content parts (text/image)
array of TextContent { text, signature, type } or ImageContent { source, type }
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
SummaryMessage object { id, date, summary, 9 more }
A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.
compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }
EventMessage object { id, date, event_data, 9 more }
A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.
MessageSearchResponse = array of object { content, created_at, message_id, 3 more } or object { content, created_at, message_id, 3 more } or object { created_at, message_id, reasoning, 3 more } or object { content, created_at, message_id, 3 more }
SystemMessage object { content, created_at, message_id, 3 more }
System message list result with agent context.
Shape is identical to UpdateSystemMessage but includes the owning agent_id and message id.
UserMessage object { content, created_at, message_id, 3 more }
User message list result with agent context.
Shape is identical to UpdateUserMessage but includes the owning agent_id and message id.
The message content sent by the user (can be a string or an array of multi-modal content parts)
array of LettaUserMessageContentUnion
ImageContent object { source, type }
source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }
The source of the image.
ReasoningMessage object { created_at, message_id, reasoning, 3 more }
AssistantMessage object { content, created_at, message_id, 3 more }
Assistant message list result with agent context.
Shape is identical to UpdateAssistantMessage but includes the owning agent_id and message id.
The message content sent by the assistant (can be a string or an array of content parts)