## 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 Parameters

- `conversation_id: string`

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

### Query Parameters

- `after: optional string`

  Cursor for pagination (message ID). Returns results relative to this ID in the specified sort order. Expected format: 'message-<uuid4>'

- `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-<uuid4>'

- `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.

  - `"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

- `order: optional "asc" or "desc"`

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

  - `"asc"`

  - `"desc"`

- `order_by: optional "created_at"`

  Field to sort by

  - `"created_at"`

### Returns

- `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.

    - `"system_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)

    - `array of LettaUserMessageContentUnion`

      - `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.

          - `"text"`

      - `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.

          - `URL object { url, type }`

            - `url: string`

              The URL of the image.

            - `type: optional "url"`

              The source type for the image.

              - `"url"`

          - `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.

              - `"base64"`

          - `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.

              - `"letta"`

        - `type: optional "image"`

          The type of the message.

          - `"image"`

    - `string`

  - `date: string`

  - `is_err: optional boolean`

  - `message_type: optional "user_message"`

    The type of the message.

    - `"user_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.

    - `"reasoning_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"`

    - `"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"`

    - `"redacted"`

    - `"omitted"`

  - `hidden_reasoning: optional string`

  - `is_err: optional boolean`

  - `message_type: optional "hidden_reasoning_message"`

    The type of the message.

    - `"hidden_reasoning_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`

  - `tool_call: ToolCall or ToolCallDelta`

    - `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.

    - `"tool_call_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 or ToolCallDelta`

    - `array of ToolCall`

      - `arguments: string`

      - `name: string`

      - `tool_call_id: string`

    - `ToolCallDelta object { 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

  - `id: string`

  - `date: string`

  - `status: "success" or "error"`

    - `"success"`

    - `"error"`

  - `tool_call_id: string`

  - `tool_return: string`

  - `is_err: optional boolean`

  - `message_type: optional "tool_return_message"`

    The type of the message.

    - `"tool_return_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`

  - `stderr: optional array of string`

  - `stdout: optional array of string`

  - `step_id: optional string`

  - `tool_returns: optional array of ToolReturn`

    - `status: "success" or "error"`

      - `"success"`

      - `"error"`

    - `tool_call_id: string`

    - `tool_return: array of TextContent or ImageContent or string`

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

      - `array of TextContent or ImageContent`

        - `TextContent object { text, signature, type }`

        - `ImageContent object { source, type }`

      - `string`

    - `stderr: optional array of string`

    - `stdout: optional array of string`

    - `type: optional "tool"`

      The message type to be created.

      - `"tool"`

- `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 or string`

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

    - `array of LettaAssistantMessageContentUnion`

      - `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.

        - `"text"`

    - `string`

  - `date: string`

  - `is_err: optional boolean`

  - `message_type: optional "assistant_message"`

    The type of the message.

    - `"assistant_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`

  - `tool_call: ToolCall or ToolCallDelta`

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

    - `ToolCall object { arguments, name, tool_call_id }`

    - `ToolCallDelta object { arguments, name, tool_call_id }`

  - `is_err: optional boolean`

  - `message_type: optional "approval_request_message"`

    The type of the message.

    - `"approval_request_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 or ToolCallDelta`

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

    - `array of ToolCall`

      - `arguments: string`

      - `name: string`

      - `tool_call_id: string`

    - `ToolCallDelta object { 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

  - `id: string`

  - `date: string`

  - `approval_request_id: optional string`

    The message ID of the approval request

  - `approvals: optional array of ApprovalReturn or ToolReturn`

    The list of approval responses

    - `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.

        - `"approval"`

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

      - `status: "success" or "error"`

      - `tool_call_id: string`

      - `tool_return: array of TextContent or ImageContent or string`

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

      - `stderr: optional array of string`

      - `stdout: optional array of string`

      - `type: optional "tool"`

        The message type to be created.

  - `approve: optional boolean`

    Whether the tool has been approved

  - `is_err: optional boolean`

  - `message_type: optional "approval_response_message"`

    The type of the message.

    - `"approval_response_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.

  - `reason: 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"`

    - `"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"`

    - `"compaction"`

  - `is_err: optional boolean`

  - `message_type: optional "event_message"`

    - `"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`

### Example

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

#### Response

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