API Reference

Conversations

Messages

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Conversation Messages

GET/v1/conversations/{conversation_id}/messages

List all messages in a conversation.

Returns LettaMessage objects (UserMessage, AssistantMessage, etc.) for all messages in the conversation, with support for cursor-based pagination.

Agent-direct mode: Pass conversation_id=“default” with agent_id parameter to list messages from the agent’s default conversation.

Deprecated: Passing an agent ID as conversation_id still works but will be removed.

Path ParametersExpand Collapse

conversation_id: string

The conversation identifier. Can be a conversation ID (‘conv-’), ‘default’ for agent-direct mode (with agent_id parameter), or an agent ID (‘agent-’) for backwards compatibility (deprecated).

minLength1

maxLength42

Query ParametersExpand Collapse

after: optional string

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

minLength44

maxLength44

agent_id: optional string

Agent ID for agent-direct mode with ‘default’ conversation

before: optional string

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

minLength44

maxLength44

group_id: optional string

Group ID to filter messages by.

include_err: optional boolean

Whether to include error messages and error statuses. For debugging purposes only.

include_return_message_types: optional array of MessageType

Message types to include in response. When null, all message types are returned.

One of the following:

"system_message"

"user_message"

"assistant_message"

"reasoning_message"

"hidden_reasoning_message"

"tool_call_message"

"tool_return_message"

"approval_request_message"

"approval_response_message"

"summary_message"

"event_message"

limit: optional number

Maximum number of messages to return

maximum200

order: optional "asc" or "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 "created_at"

Field to sort by

ReturnsExpand Collapse

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

id: string

content: string

The message content sent by the system

date: string

is_err: optional boolean

message_type: optional "system_message"

The type of the message.

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

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)

id: string

content: array of LettaUserMessageContentUnion or string

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

One of the following:

array of LettaUserMessageContentUnion

One of the following:

TextContent object { text, signature, type }

text: string

The text content of the message.

signature: optional string

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

type: optional "text"

The type 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.

One of the following:

URL object { url, type }

url: string

The URL of the image.

type: optional "url"

The source type for the image.

Base64 object { data, media_type, detail, type }

data: string

The base64 encoded image data.

media_type: string

The media type for the image.

detail: optional string

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

type: optional "base64"

The source type for the image.

Letta object { file_id, data, detail, 2 more }

file_id: string

The unique identifier of the image file persisted in storage.

data: optional string

The base64 encoded image data.

detail: optional string

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

media_type: optional string

The media type for the image.

type: optional "letta"

The source type for the image.

type: optional "image"

The type of the message.

string

date: string

is_err: optional boolean

message_type: optional "user_message"

The type of the message.

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

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

id: string

date: string

reasoning: string

is_err: optional boolean

message_type: optional "reasoning_message"

The type of the message.

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

signature: optional string

source: optional "reasoner_model" or "non_reasoner_model"

One of the following:

"reasoner_model"

"non_reasoner_model"

step_id: optional string

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

id: string

date: string

state: "redacted" or "omitted"

One of the following:

"redacted"

"omitted"

hidden_reasoning: optional string

is_err: optional boolean

message_type: optional "hidden_reasoning_message"

The type of the message.

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

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

id: string

date: string

Deprecatedtool_call: ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }

One of the following:

ToolCall object { arguments, name, tool_call_id }

arguments: string

name: string

tool_call_id: string

ToolCallDelta object { arguments, name, tool_call_id }

arguments: optional string

name: optional string

tool_call_id: optional string

is_err: optional boolean

message_type: optional "tool_call_message"

The type of the message.

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

tool_calls: optional array of ToolCall { arguments, name, tool_call_id } or ToolCallDelta { arguments, name, tool_call_id }

One of the following:

array of ToolCall { arguments, name, tool_call_id }

arguments: string

name: string

tool_call_id: string

ToolCallDelta object { arguments, name, tool_call_id }

arguments: optional string

name: optional string

tool_call_id: optional string

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

id: string

date: string

Deprecatedstatus: "success" or "error"

One of the following:

"success"

"error"

Deprecatedtool_call_id: string

Deprecatedtool_return: string

is_err: optional boolean

message_type: optional "tool_return_message"

The type of the message.

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

Deprecatedstderr: optional array of string

Deprecatedstdout: optional array of string

step_id: optional string

tool_returns: optional array of ToolReturn { status, tool_call_id, tool_return, 3 more }

status: "success" or "error"

One of the following:

"success"

"error"

tool_call_id: string

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)

One of the following:

array of TextContent { text, signature, type } or ImageContent { source, type }

One of the following:

TextContent object { text, signature, type }

text: string

The text content of the message.

signature: optional string

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

type: optional "text"

The type 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.

One of the following:

URL object { url, type }

url: string

The URL of the image.

type: optional "url"

The source type for the image.

Base64 object { data, media_type, detail, type }

data: string

The base64 encoded image data.

media_type: string

The media type for the image.

detail: optional string

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

type: optional "base64"

The source type for the image.

Letta object { file_id, data, detail, 2 more }

file_id: string

The unique identifier of the image file persisted in storage.

data: optional string

The base64 encoded image data.

detail: optional string

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

media_type: optional string

The media type for the image.

type: optional "letta"

The source type for the image.

type: optional "image"

The type of the message.

string

stderr: optional array of string

stdout: optional array of string

type: optional "tool"

The message type to be created.

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)

id: string

content: array of LettaAssistantMessageContentUnion { text, signature, type } or string

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

One of the following:

array of LettaAssistantMessageContentUnion { text, signature, type }

text: string

The text content of the message.

signature: optional string

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

type: optional "text"

The type of the message.

string

date: string

is_err: optional boolean

message_type: optional "assistant_message"

The type of the message.

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

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

id: string

date: string

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

One of the following:

ToolCall object { arguments, name, tool_call_id }

arguments: string

name: string

tool_call_id: string

ToolCallDelta object { arguments, name, tool_call_id }

arguments: optional string

name: optional string

tool_call_id: optional string

is_err: optional boolean

message_type: optional "approval_request_message"

The type of the message.

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

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

One of the following:

array of ToolCall { arguments, name, tool_call_id }

arguments: string

name: string

tool_call_id: string

ToolCallDelta object { arguments, name, tool_call_id }

arguments: optional string

name: optional string

tool_call_id: optional string

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

id: string

date: string

Deprecatedapproval_request_id: optional string

The message ID of the approval request

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

One of the following:

ApprovalReturn object { approve, tool_call_id, reason, type }

approve: boolean

Whether the tool has been approved

tool_call_id: string

The ID of the tool call that corresponds to this approval

reason: optional string

An optional explanation for the provided approval status

type: optional "approval"

The message type to be created.

ToolReturn object { status, tool_call_id, tool_return, 3 more }

status: "success" or "error"

One of the following:

"success"

"error"

tool_call_id: string

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)

One of the following:

array of TextContent { text, signature, type } or ImageContent { source, type }

One of the following:

TextContent object { text, signature, type }

text: string

The text content of the message.

signature: optional string

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

type: optional "text"

The type 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.

One of the following:

URL object { url, type }

url: string

The URL of the image.

type: optional "url"

The source type for the image.

Base64 object { data, media_type, detail, type }

data: string

The base64 encoded image data.

media_type: string

The media type for the image.

detail: optional string

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

type: optional "base64"

The source type for the image.

Letta object { file_id, data, detail, 2 more }

file_id: string

The unique identifier of the image file persisted in storage.

data: optional string

The base64 encoded image data.

detail: optional string

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

media_type: optional string

The media type for the image.

type: optional "letta"

The source type for the image.

type: optional "image"

The type of the message.

string

stderr: optional array of string

stdout: optional array of string

type: optional "tool"

The message type to be created.

Deprecatedapprove: optional boolean

Whether the tool has been approved

is_err: optional boolean

message_type: optional "approval_response_message"

The type of the message.

name: optional string

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.

Deprecatedreason: optional string

An optional explanation for the provided approval status

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

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.

id: string

date: string

summary: string

compaction_stats: optional object { context_window, messages_count_after, messages_count_before, 3 more }

Statistics about a memory compaction operation.

context_window: number

The model’s context window size

messages_count_after: number

Number of messages after compaction

messages_count_before: number

Number of messages before compaction

trigger: string

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

context_tokens_after: optional number

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

context_tokens_before: optional number

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

is_err: optional boolean

message_type: optional "summary_message"

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

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.

id: string

date: string

event_data: map[unknown]

event_type: "compaction"

is_err: optional boolean

message_type: optional "event_message"

name: optional string

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.

run_id: optional string

sender_id: optional string

seq_id: optional number

step_id: optional string

List Conversation Messages

HTTP

HTTP

TypeScript

Python

curl https://api.letta.com/v1/conversations/$CONVERSATION_ID/messages \
    -H "Authorization: Bearer $LETTA_API_KEY"

200 example

[
  {
    "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

200 example

[
  {
    "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"
  }
]