# Messages

## List All Messages

**get** `/v1/messages/`

List messages across all agents for the current user.

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

- `before: optional string`

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

- `conversation_id: optional string`

  Conversation ID to filter messages by

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

### 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/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"
  }
]
```

## Retrieve Message

**get** `/v1/messages/{message_id}`

Retrieve a message by ID.

### Path Parameters

- `message_id: string`

  The ID of the message in the format 'message-<uuid4>'

### 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/messages/$MESSAGE_ID \
    -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"
  }
]
```

## Search All Messages

**post** `/v1/messages/search`

Search messages across the organization with optional agent filtering.
Returns messages with FTS/vector ranks and total RRF score.

This is a cloud-only feature.

### Body Parameters

- `query: string`

  Text query for full-text search

- `agent_id: optional string`

  Filter messages by agent ID

- `conversation_id: optional string`

  Filter messages by conversation ID

- `end_date: optional string`

  Filter messages created on or before this date

- `limit: optional number`

  Maximum number of results to return

- `search_mode: optional "vector" or "fts" or "hybrid"`

  Search mode to use

  - `"vector"`

  - `"fts"`

  - `"hybrid"`

- `start_date: optional string`

  Filter messages created after this date

### Returns

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

  - `content: string`

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

  - `created_at: string`

    The time the message was created in ISO format.

  - `message_id: string`

    The unique identifier of the message.

  - `agent_id: optional string`

    The unique identifier of the agent that owns the message.

  - `conversation_id: optional string`

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

  - `message_type: optional "system_message"`

    - `"system_message"`

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

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

  - `created_at: string`

    The time the message was created in ISO format.

  - `message_id: string`

    The unique identifier of the message.

  - `agent_id: optional string`

    The unique identifier of the agent that owns the message.

  - `conversation_id: optional string`

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

  - `message_type: optional "user_message"`

    - `"user_message"`

- `ReasoningMessage object { created_at, message_id, reasoning, 3 more }`

  Reasoning message list result with agent context.

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

  - `created_at: string`

    The time the message was created in ISO format.

  - `message_id: string`

    The unique identifier of the message.

  - `reasoning: string`

  - `agent_id: optional string`

    The unique identifier of the agent that owns the message.

  - `conversation_id: optional string`

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

  - `message_type: optional "reasoning_message"`

    - `"reasoning_message"`

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

  - `content: array of LettaAssistantMessageContentUnion or string`

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

  - `created_at: string`

    The time the message was created in ISO format.

  - `message_id: string`

    The unique identifier of the message.

  - `agent_id: optional string`

    The unique identifier of the agent that owns the message.

  - `conversation_id: optional string`

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

  - `message_type: optional "assistant_message"`

    - `"assistant_message"`

### Example

```http
curl https://api.letta.com/v1/messages/search \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LETTA_API_KEY" \
    -d '{
          "query": "query"
        }'
```

#### Response

```json
[
  {
    "content": "content",
    "created_at": "2019-12-27T18:11:19.117Z",
    "message_id": "message_id",
    "agent_id": "agent_id",
    "conversation_id": "conversation_id",
    "message_type": "system_message"
  }
]
```

## Domain Types

### Message Search Request

- `MessageSearchRequest object { query, agent_id, conversation_id, 4 more }`

  - `query: string`

    Text query for full-text search

  - `agent_id: optional string`

    Filter messages by agent ID

  - `conversation_id: optional string`

    Filter messages by conversation ID

  - `end_date: optional string`

    Filter messages created on or before this date

  - `limit: optional number`

    Maximum number of results to return

  - `search_mode: optional "vector" or "fts" or "hybrid"`

    Search mode to use

    - `"vector"`

    - `"fts"`

    - `"hybrid"`

  - `start_date: optional string`

    Filter messages created after this date

### Message Search Result

- `MessageSearchResult object { embedded_text, message, rrf_score, 2 more }`

  Result from a message search operation with scoring details.

  - `embedded_text: string`

    The embedded content (LLM-friendly)

  - `message: InternalMessage`

    The raw message object

    - `id: string`

      The human-friendly ID of the Message

    - `role: MessageRole`

      The role of the participant.

      - `"assistant"`

      - `"user"`

      - `"tool"`

      - `"function"`

      - `"system"`

      - `"approval"`

      - `"summary"`

    - `agent_id: optional string`

      The unique identifier of the agent.

    - `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 or object { status, func_response, stderr, 2 more }`

      The list of approvals for this message.

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

      - `LettaSchemasMessageToolReturnOutput object { status, func_response, stderr, 2 more }`

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

          The status of the tool call

          - `"success"`

          - `"error"`

        - `func_response: optional string or array of TextContent or ImageContent`

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

          - `string`

          - `array of TextContent or ImageContent`

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

        - `stderr: optional array of string`

          Captured stderr from the tool invocation

        - `stdout: optional array of string`

          Captured stdout (e.g. prints, logs) from the tool invocation

        - `tool_call_id: optional unknown`

          The ID for the tool call

    - `approve: optional boolean`

      Whether tool call is approved.

    - `batch_item_id: optional string`

      The id of the LLMBatchItem that this message is associated with

    - `content: optional array of TextContent or ImageContent or ToolCallContent or 5 more`

      The content of the message.

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

      - `ImageContent object { source, type }`

      - `ToolCallContent object { id, input, name, 2 more }`

        - `id: string`

          A unique identifier for this specific tool call instance.

        - `input: map[unknown]`

          The parameters being passed to the tool, structured as a dictionary of parameter names to values.

        - `name: string`

          The name of the tool being called.

        - `signature: optional string`

          Stores a unique identifier for any reasoning associated with this tool call.

        - `type: optional "tool_call"`

          Indicates this content represents a tool call event.

          - `"tool_call"`

      - `ToolReturnContent object { content, is_error, tool_call_id, type }`

        - `content: string`

          The content returned by the tool execution.

        - `is_error: boolean`

          Indicates whether the tool execution resulted in an error.

        - `tool_call_id: string`

          References the ID of the ToolCallContent that initiated this tool call.

        - `type: optional "tool_return"`

          Indicates this content represents a tool return event.

          - `"tool_return"`

      - `ReasoningContent object { is_native, reasoning, signature, type }`

        Sent via the Anthropic Messages API

        - `is_native: boolean`

          Whether the reasoning content was generated by a reasoner model that processed this step.

        - `reasoning: string`

          The intermediate reasoning or thought process content.

        - `signature: optional string`

          A unique identifier for this reasoning step.

        - `type: optional "reasoning"`

          Indicates this is a reasoning/intermediate step.

          - `"reasoning"`

      - `RedactedReasoningContent object { data, type }`

        Sent via the Anthropic Messages API

        - `data: string`

          The redacted or filtered intermediate reasoning content.

        - `type: optional "redacted_reasoning"`

          Indicates this is a redacted thinking step.

          - `"redacted_reasoning"`

      - `OmittedReasoningContent object { signature, type }`

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

          A unique identifier for this reasoning step.

        - `type: optional "omitted_reasoning"`

          Indicates this is an omitted reasoning step.

          - `"omitted_reasoning"`

      - `SummarizedReasoning object { id, summary, encrypted_content, type }`

        The style of reasoning content returned by the OpenAI Responses API

        - `id: string`

          The unique identifier for this reasoning step.

        - `summary: array of object { index, text }`

          Summaries of the reasoning content.

          - `index: number`

            The index of the summary part.

          - `text: string`

            The text of the summary part.

        - `encrypted_content: optional string`

          The encrypted reasoning content.

        - `type: optional "summarized_reasoning"`

          Indicates this is a summarized reasoning step.

          - `"summarized_reasoning"`

    - `conversation_id: optional string`

      The conversation this message belongs to

    - `created_at: optional string`

      The timestamp when the object was created.

    - `created_by_id: optional string`

      The id of the user that made this object.

    - `denial_reason: optional string`

      The reason the tool call request was denied.

    - `group_id: optional string`

      The multi-agent group that the message was sent in

    - `is_err: optional boolean`

      Whether this message is part of an error step. Used only for debugging purposes.

    - `last_updated_by_id: optional string`

      The id of the user that made this object.

    - `model: optional string`

      The model used to make the function call.

    - `name: optional string`

      For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.

    - `otid: optional string`

      The offline threading id associated with this message

    - `run_id: optional string`

      The id of the run that this message was created in.

    - `sender_id: optional string`

      The id of the sender of the message, can be an identity id or agent id

    - `step_id: optional string`

      The id of the step that this message was created in.

    - `tool_call_id: optional string`

      The ID of the tool call. Only applicable for role tool.

    - `tool_calls: optional array of object { id, function, type }`

      The list of tool calls requested. Only applicable for role assistant.

      - `id: string`

      - `function: object { arguments, name }`

        The function that the model called.

        - `arguments: string`

        - `name: string`

      - `type: "function"`

        - `"function"`

    - `tool_returns: optional array of object { status, func_response, stderr, 2 more }`

      Tool execution return information for prior tool calls

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

        The status of the tool call

        - `"success"`

        - `"error"`

      - `func_response: optional string or array of TextContent or ImageContent`

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

        - `string`

        - `array of TextContent or ImageContent`

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

          - `ImageContent object { source, type }`

      - `stderr: optional array of string`

        Captured stderr from the tool invocation

      - `stdout: optional array of string`

        Captured stdout (e.g. prints, logs) from the tool invocation

      - `tool_call_id: optional unknown`

        The ID for the tool call

    - `updated_at: optional string`

      The timestamp when the object was last updated.

  - `rrf_score: number`

    Reciprocal Rank Fusion combined score

  - `fts_rank: optional number`

    Full-text search rank position if FTS was used

  - `vector_rank: optional number`

    Vector search rank position if vector search was used

### Message List Response

- `MessageListResponse = array of Message`

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

### Message Retrieve Response

- `MessageRetrieveResponse = array of Message`

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

### Message Search Response

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

    - `content: string`

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

    - `created_at: string`

      The time the message was created in ISO format.

    - `message_id: string`

      The unique identifier of the message.

    - `agent_id: optional string`

      The unique identifier of the agent that owns the message.

    - `conversation_id: optional string`

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

    - `message_type: optional "system_message"`

      - `"system_message"`

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

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

    - `created_at: string`

      The time the message was created in ISO format.

    - `message_id: string`

      The unique identifier of the message.

    - `agent_id: optional string`

      The unique identifier of the agent that owns the message.

    - `conversation_id: optional string`

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

    - `message_type: optional "user_message"`

      - `"user_message"`

  - `ReasoningMessage object { created_at, message_id, reasoning, 3 more }`

    Reasoning message list result with agent context.

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

    - `created_at: string`

      The time the message was created in ISO format.

    - `message_id: string`

      The unique identifier of the message.

    - `reasoning: string`

    - `agent_id: optional string`

      The unique identifier of the agent that owns the message.

    - `conversation_id: optional string`

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

    - `message_type: optional "reasoning_message"`

      - `"reasoning_message"`

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

    - `content: array of LettaAssistantMessageContentUnion or string`

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

    - `created_at: string`

      The time the message was created in ISO format.

    - `message_id: string`

      The unique identifier of the message.

    - `agent_id: optional string`

      The unique identifier of the agent that owns the message.

    - `conversation_id: optional string`

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

    - `message_type: optional "assistant_message"`

      - `"assistant_message"`