# Messages

## List All Messages

`messages.list(MessageListParams**kwargs)  -> MessageListResponse`

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

List messages across all agents for the current user.

### Parameters

- `after: Optional[str]`

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

- `before: Optional[str]`

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

- `conversation_id: Optional[str]`

  Conversation ID to filter messages by

- `include_return_message_types: Optional[List[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[int]`

  Maximum number of messages to return

- `order: Optional[Literal["asc", "desc"]]`

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

  - `"asc"`

  - `"desc"`

### Returns

- `List[Message]`

  - `class SystemMessage: …`

    A message generated by the system. Never streamed back on a response, only used for cursor pagination.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (str): The message content sent by the system

    - `id: str`

    - `content: str`

      The message content sent by the system

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["system_message"]]`

      The type of the message.

      - `"system_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class UserMessage: …`

    A message sent by the user. Never streamed back on a response, only used for cursor pagination.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)

    - `id: str`

    - `content: Union[List[LettaUserMessageContentUnion], str]`

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

      - `List[LettaUserMessageContentUnion]`

        - `class TextContent: …`

          - `text: str`

            The text content of the message.

          - `signature: Optional[str]`

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

          - `type: Optional[Literal["text"]]`

            The type of the message.

            - `"text"`

        - `class ImageContent: …`

          - `source: Source`

            The source of the image.

            - `class SourceURLImage: …`

              - `url: str`

                The URL of the image.

              - `type: Optional[Literal["url"]]`

                The source type for the image.

                - `"url"`

            - `class SourceBase64Image: …`

              - `data: str`

                The base64 encoded image data.

              - `media_type: str`

                The media type for the image.

              - `detail: Optional[str]`

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

              - `type: Optional[Literal["base64"]]`

                The source type for the image.

                - `"base64"`

            - `class SourceLettaImage: …`

              - `file_id: str`

                The unique identifier of the image file persisted in storage.

              - `data: Optional[str]`

                The base64 encoded image data.

              - `detail: Optional[str]`

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

              - `media_type: Optional[str]`

                The media type for the image.

              - `type: Optional[Literal["letta"]]`

                The source type for the image.

                - `"letta"`

          - `type: Optional[Literal["image"]]`

            The type of the message.

            - `"image"`

      - `str`

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["user_message"]]`

      The type of the message.

      - `"user_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ReasoningMessage: …`

    Representation of an agent's internal reasoning.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning
    content was generated natively by a reasoner model or derived via prompting
    reasoning (str): The internal reasoning of the agent
    signature (Optional[str]): The model-generated signature of the reasoning step

    - `id: str`

    - `date: datetime`

    - `reasoning: str`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["reasoning_message"]]`

      The type of the message.

      - `"reasoning_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `signature: Optional[str]`

    - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]`

      - `"reasoner_model"`

      - `"non_reasoner_model"`

    - `step_id: Optional[str]`

  - `class HiddenReasoningMessage: …`

    Representation of an agent's internal reasoning where reasoning content
    has been hidden from the response.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    state (Literal["redacted", "omitted"]): Whether the reasoning
    content was redacted by the provider or simply omitted by the API
    hidden_reasoning (Optional[str]): The internal reasoning of the agent

    - `id: str`

    - `date: datetime`

    - `state: Literal["redacted", "omitted"]`

      - `"redacted"`

      - `"omitted"`

    - `hidden_reasoning: Optional[str]`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["hidden_reasoning_message"]]`

      The type of the message.

      - `"hidden_reasoning_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ToolCallMessage: …`

    A message representing a request to call a tool (generated by the LLM to trigger tool execution).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_call (Union[ToolCall, ToolCallDelta]): The tool call

    - `id: str`

    - `date: datetime`

    - `tool_call: ToolCall`

      - `class ToolCall: …`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

        - `arguments: Optional[str]`

        - `name: Optional[str]`

        - `tool_call_id: Optional[str]`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["tool_call_message"]]`

      The type of the message.

      - `"tool_call_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

    - `tool_calls: Optional[ToolCalls]`

      - `List[ToolCall]`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

  - `class ToolReturnMessage: …`

    A message representing the return value of a tool call (generated by Letta executing the requested tool).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_return (str): The return value of the tool (deprecated, use tool_returns)
    status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns)
    tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns)
    stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns)
    stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns)
    tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support

    - `id: str`

    - `date: datetime`

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

      - `"success"`

      - `"error"`

    - `tool_call_id: str`

    - `tool_return: str`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["tool_return_message"]]`

      The type of the message.

      - `"tool_return_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `stderr: Optional[List[str]]`

    - `stdout: Optional[List[str]]`

    - `step_id: Optional[str]`

    - `tool_returns: Optional[List[ToolReturn]]`

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

        - `"success"`

        - `"error"`

      - `tool_call_id: str`

      - `tool_return: Union[List[ToolReturnUnionMember0], str]`

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

        - `List[ToolReturnUnionMember0]`

          - `class TextContent: …`

          - `class ImageContent: …`

        - `str`

      - `stderr: Optional[List[str]]`

      - `stdout: Optional[List[str]]`

      - `type: Optional[Literal["tool"]]`

        The message type to be created.

        - `"tool"`

  - `class AssistantMessage: …`

    A message sent by the LLM in response to user input. Used in the LLM context.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)

    - `id: str`

    - `content: Union[List[LettaAssistantMessageContentUnion], str]`

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

      - `List[LettaAssistantMessageContentUnion]`

        - `text: str`

          The text content of the message.

        - `signature: Optional[str]`

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

        - `type: Optional[Literal["text"]]`

          The type of the message.

          - `"text"`

      - `str`

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["assistant_message"]]`

      The type of the message.

      - `"assistant_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ApprovalRequestMessage: …`

    A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_call (ToolCall): The tool call

    - `id: str`

    - `date: datetime`

    - `tool_call: ToolCall`

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

      - `class ToolCall: …`

      - `class ToolCallDelta: …`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["approval_request_message"]]`

      The type of the message.

      - `"approval_request_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

    - `tool_calls: Optional[ToolCalls]`

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

      - `List[ToolCall]`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

  - `class ApprovalResponseMessage: …`

    A message representing a response form the user indicating whether a tool has been approved to run.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    approve: (bool) Whether the tool has been approved
    approval_request_id: The ID of the approval request
    reason: (Optional[str]) An optional explanation for the provided approval status

    - `id: str`

    - `date: datetime`

    - `approval_request_id: Optional[str]`

      The message ID of the approval request

    - `approvals: Optional[List[Approval]]`

      The list of approval responses

      - `class ApprovalReturn: …`

        - `approve: bool`

          Whether the tool has been approved

        - `tool_call_id: str`

          The ID of the tool call that corresponds to this approval

        - `reason: Optional[str]`

          An optional explanation for the provided approval status

        - `type: Optional[Literal["approval"]]`

          The message type to be created.

          - `"approval"`

      - `class ToolReturn: …`

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

        - `tool_call_id: str`

        - `tool_return: Union[List[ToolReturnUnionMember0], str]`

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

        - `stderr: Optional[List[str]]`

        - `stdout: Optional[List[str]]`

        - `type: Optional[Literal["tool"]]`

          The message type to be created.

    - `approve: Optional[bool]`

      Whether the tool has been approved

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["approval_response_message"]]`

      The type of the message.

      - `"approval_response_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `reason: Optional[str]`

      An optional explanation for the provided approval status

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class SummaryMessage: …`

    A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.

    - `id: str`

    - `date: datetime`

    - `summary: str`

    - `compaction_stats: Optional[CompactionStats]`

      Statistics about a memory compaction operation.

      - `context_window: int`

        The model's context window size

      - `messages_count_after: int`

        Number of messages after compaction

      - `messages_count_before: int`

        Number of messages before compaction

      - `trigger: str`

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

      - `context_tokens_after: Optional[int]`

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

      - `context_tokens_before: Optional[int]`

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

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["summary_message"]]`

      - `"summary_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class EventMessage: …`

    A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.

    - `id: str`

    - `date: datetime`

    - `event_data: Dict[str, object]`

    - `event_type: Literal["compaction"]`

      - `"compaction"`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["event_message"]]`

      - `"event_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

### Example

```python
import os
from letta_client import Letta

client = Letta(
    api_key=os.environ.get("LETTA_API_KEY"),  # This is the default and can be omitted
)
messages = client.messages.list()
print(messages)
```

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

`messages.retrieve(strmessage_id)  -> MessageRetrieveResponse`

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

Retrieve a message by ID.

### Parameters

- `message_id: str`

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

### Returns

- `List[Message]`

  - `class SystemMessage: …`

    A message generated by the system. Never streamed back on a response, only used for cursor pagination.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (str): The message content sent by the system

    - `id: str`

    - `content: str`

      The message content sent by the system

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["system_message"]]`

      The type of the message.

      - `"system_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class UserMessage: …`

    A message sent by the user. Never streamed back on a response, only used for cursor pagination.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)

    - `id: str`

    - `content: Union[List[LettaUserMessageContentUnion], str]`

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

      - `List[LettaUserMessageContentUnion]`

        - `class TextContent: …`

          - `text: str`

            The text content of the message.

          - `signature: Optional[str]`

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

          - `type: Optional[Literal["text"]]`

            The type of the message.

            - `"text"`

        - `class ImageContent: …`

          - `source: Source`

            The source of the image.

            - `class SourceURLImage: …`

              - `url: str`

                The URL of the image.

              - `type: Optional[Literal["url"]]`

                The source type for the image.

                - `"url"`

            - `class SourceBase64Image: …`

              - `data: str`

                The base64 encoded image data.

              - `media_type: str`

                The media type for the image.

              - `detail: Optional[str]`

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

              - `type: Optional[Literal["base64"]]`

                The source type for the image.

                - `"base64"`

            - `class SourceLettaImage: …`

              - `file_id: str`

                The unique identifier of the image file persisted in storage.

              - `data: Optional[str]`

                The base64 encoded image data.

              - `detail: Optional[str]`

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

              - `media_type: Optional[str]`

                The media type for the image.

              - `type: Optional[Literal["letta"]]`

                The source type for the image.

                - `"letta"`

          - `type: Optional[Literal["image"]]`

            The type of the message.

            - `"image"`

      - `str`

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["user_message"]]`

      The type of the message.

      - `"user_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ReasoningMessage: …`

    Representation of an agent's internal reasoning.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning
    content was generated natively by a reasoner model or derived via prompting
    reasoning (str): The internal reasoning of the agent
    signature (Optional[str]): The model-generated signature of the reasoning step

    - `id: str`

    - `date: datetime`

    - `reasoning: str`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["reasoning_message"]]`

      The type of the message.

      - `"reasoning_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `signature: Optional[str]`

    - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]`

      - `"reasoner_model"`

      - `"non_reasoner_model"`

    - `step_id: Optional[str]`

  - `class HiddenReasoningMessage: …`

    Representation of an agent's internal reasoning where reasoning content
    has been hidden from the response.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    state (Literal["redacted", "omitted"]): Whether the reasoning
    content was redacted by the provider or simply omitted by the API
    hidden_reasoning (Optional[str]): The internal reasoning of the agent

    - `id: str`

    - `date: datetime`

    - `state: Literal["redacted", "omitted"]`

      - `"redacted"`

      - `"omitted"`

    - `hidden_reasoning: Optional[str]`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["hidden_reasoning_message"]]`

      The type of the message.

      - `"hidden_reasoning_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ToolCallMessage: …`

    A message representing a request to call a tool (generated by the LLM to trigger tool execution).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_call (Union[ToolCall, ToolCallDelta]): The tool call

    - `id: str`

    - `date: datetime`

    - `tool_call: ToolCall`

      - `class ToolCall: …`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

        - `arguments: Optional[str]`

        - `name: Optional[str]`

        - `tool_call_id: Optional[str]`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["tool_call_message"]]`

      The type of the message.

      - `"tool_call_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

    - `tool_calls: Optional[ToolCalls]`

      - `List[ToolCall]`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

  - `class ToolReturnMessage: …`

    A message representing the return value of a tool call (generated by Letta executing the requested tool).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_return (str): The return value of the tool (deprecated, use tool_returns)
    status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns)
    tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns)
    stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns)
    stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns)
    tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support

    - `id: str`

    - `date: datetime`

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

      - `"success"`

      - `"error"`

    - `tool_call_id: str`

    - `tool_return: str`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["tool_return_message"]]`

      The type of the message.

      - `"tool_return_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `stderr: Optional[List[str]]`

    - `stdout: Optional[List[str]]`

    - `step_id: Optional[str]`

    - `tool_returns: Optional[List[ToolReturn]]`

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

        - `"success"`

        - `"error"`

      - `tool_call_id: str`

      - `tool_return: Union[List[ToolReturnUnionMember0], str]`

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

        - `List[ToolReturnUnionMember0]`

          - `class TextContent: …`

          - `class ImageContent: …`

        - `str`

      - `stderr: Optional[List[str]]`

      - `stdout: Optional[List[str]]`

      - `type: Optional[Literal["tool"]]`

        The message type to be created.

        - `"tool"`

  - `class AssistantMessage: …`

    A message sent by the LLM in response to user input. Used in the LLM context.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)

    - `id: str`

    - `content: Union[List[LettaAssistantMessageContentUnion], str]`

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

      - `List[LettaAssistantMessageContentUnion]`

        - `text: str`

          The text content of the message.

        - `signature: Optional[str]`

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

        - `type: Optional[Literal["text"]]`

          The type of the message.

          - `"text"`

      - `str`

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["assistant_message"]]`

      The type of the message.

      - `"assistant_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ApprovalRequestMessage: …`

    A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_call (ToolCall): The tool call

    - `id: str`

    - `date: datetime`

    - `tool_call: ToolCall`

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

      - `class ToolCall: …`

      - `class ToolCallDelta: …`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["approval_request_message"]]`

      The type of the message.

      - `"approval_request_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

    - `tool_calls: Optional[ToolCalls]`

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

      - `List[ToolCall]`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

  - `class ApprovalResponseMessage: …`

    A message representing a response form the user indicating whether a tool has been approved to run.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    approve: (bool) Whether the tool has been approved
    approval_request_id: The ID of the approval request
    reason: (Optional[str]) An optional explanation for the provided approval status

    - `id: str`

    - `date: datetime`

    - `approval_request_id: Optional[str]`

      The message ID of the approval request

    - `approvals: Optional[List[Approval]]`

      The list of approval responses

      - `class ApprovalReturn: …`

        - `approve: bool`

          Whether the tool has been approved

        - `tool_call_id: str`

          The ID of the tool call that corresponds to this approval

        - `reason: Optional[str]`

          An optional explanation for the provided approval status

        - `type: Optional[Literal["approval"]]`

          The message type to be created.

          - `"approval"`

      - `class ToolReturn: …`

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

        - `tool_call_id: str`

        - `tool_return: Union[List[ToolReturnUnionMember0], str]`

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

        - `stderr: Optional[List[str]]`

        - `stdout: Optional[List[str]]`

        - `type: Optional[Literal["tool"]]`

          The message type to be created.

    - `approve: Optional[bool]`

      Whether the tool has been approved

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["approval_response_message"]]`

      The type of the message.

      - `"approval_response_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `reason: Optional[str]`

      An optional explanation for the provided approval status

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class SummaryMessage: …`

    A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.

    - `id: str`

    - `date: datetime`

    - `summary: str`

    - `compaction_stats: Optional[CompactionStats]`

      Statistics about a memory compaction operation.

      - `context_window: int`

        The model's context window size

      - `messages_count_after: int`

        Number of messages after compaction

      - `messages_count_before: int`

        Number of messages before compaction

      - `trigger: str`

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

      - `context_tokens_after: Optional[int]`

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

      - `context_tokens_before: Optional[int]`

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

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["summary_message"]]`

      - `"summary_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class EventMessage: …`

    A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.

    - `id: str`

    - `date: datetime`

    - `event_data: Dict[str, object]`

    - `event_type: Literal["compaction"]`

      - `"compaction"`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["event_message"]]`

      - `"event_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

### Example

```python
import os
from letta_client import Letta

client = Letta(
    api_key=os.environ.get("LETTA_API_KEY"),  # This is the default and can be omitted
)
messages = client.messages.retrieve(
    "message-123e4567-e89b-42d3-8456-426614174000",
)
print(messages)
```

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

`messages.search(MessageSearchParams**kwargs)  -> MessageSearchResponse`

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

### Parameters

- `query: str`

  Text query for full-text search

- `agent_id: Optional[str]`

  Filter messages by agent ID

- `conversation_id: Optional[str]`

  Filter messages by conversation ID

- `end_date: Optional[Union[str, datetime, null]]`

  Filter messages created on or before this date

- `limit: Optional[int]`

  Maximum number of results to return

- `search_mode: Optional[Literal["vector", "fts", "hybrid"]]`

  Search mode to use

  - `"vector"`

  - `"fts"`

  - `"hybrid"`

- `start_date: Optional[Union[str, datetime, null]]`

  Filter messages created after this date

### Returns

- `List[MessageSearchResponseItem]`

  - `class MessageSearchResponseItemSystemMessageListResult: …`

    System message list result with agent context.

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

    - `content: str`

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

    - `created_at: datetime`

      The time the message was created in ISO format.

    - `message_id: str`

      The unique identifier of the message.

    - `agent_id: Optional[str]`

      The unique identifier of the agent that owns the message.

    - `conversation_id: Optional[str]`

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

    - `message_type: Optional[Literal["system_message"]]`

      - `"system_message"`

  - `class MessageSearchResponseItemUserMessageListResult: …`

    User message list result with agent context.

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

    - `content: Union[List[LettaUserMessageContentUnion], str]`

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

      - `List[LettaUserMessageContentUnion]`

        - `class TextContent: …`

          - `text: str`

            The text content of the message.

          - `signature: Optional[str]`

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

          - `type: Optional[Literal["text"]]`

            The type of the message.

            - `"text"`

        - `class ImageContent: …`

          - `source: Source`

            The source of the image.

            - `class SourceURLImage: …`

              - `url: str`

                The URL of the image.

              - `type: Optional[Literal["url"]]`

                The source type for the image.

                - `"url"`

            - `class SourceBase64Image: …`

              - `data: str`

                The base64 encoded image data.

              - `media_type: str`

                The media type for the image.

              - `detail: Optional[str]`

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

              - `type: Optional[Literal["base64"]]`

                The source type for the image.

                - `"base64"`

            - `class SourceLettaImage: …`

              - `file_id: str`

                The unique identifier of the image file persisted in storage.

              - `data: Optional[str]`

                The base64 encoded image data.

              - `detail: Optional[str]`

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

              - `media_type: Optional[str]`

                The media type for the image.

              - `type: Optional[Literal["letta"]]`

                The source type for the image.

                - `"letta"`

          - `type: Optional[Literal["image"]]`

            The type of the message.

            - `"image"`

      - `str`

    - `created_at: datetime`

      The time the message was created in ISO format.

    - `message_id: str`

      The unique identifier of the message.

    - `agent_id: Optional[str]`

      The unique identifier of the agent that owns the message.

    - `conversation_id: Optional[str]`

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

    - `message_type: Optional[Literal["user_message"]]`

      - `"user_message"`

  - `class MessageSearchResponseItemReasoningMessageListResult: …`

    Reasoning message list result with agent context.

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

    - `created_at: datetime`

      The time the message was created in ISO format.

    - `message_id: str`

      The unique identifier of the message.

    - `reasoning: str`

    - `agent_id: Optional[str]`

      The unique identifier of the agent that owns the message.

    - `conversation_id: Optional[str]`

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

    - `message_type: Optional[Literal["reasoning_message"]]`

      - `"reasoning_message"`

  - `class MessageSearchResponseItemAssistantMessageListResult: …`

    Assistant message list result with agent context.

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

    - `content: Union[List[LettaAssistantMessageContentUnion], str]`

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

      - `List[LettaAssistantMessageContentUnion]`

        - `text: str`

          The text content of the message.

        - `signature: Optional[str]`

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

        - `type: Optional[Literal["text"]]`

          The type of the message.

          - `"text"`

      - `str`

    - `created_at: datetime`

      The time the message was created in ISO format.

    - `message_id: str`

      The unique identifier of the message.

    - `agent_id: Optional[str]`

      The unique identifier of the agent that owns the message.

    - `conversation_id: Optional[str]`

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

    - `message_type: Optional[Literal["assistant_message"]]`

      - `"assistant_message"`

### Example

```python
import os
from letta_client import Letta

client = Letta(
    api_key=os.environ.get("LETTA_API_KEY"),  # This is the default and can be omitted
)
response = client.messages.search(
    query="query",
)
print(response)
```

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

- `class MessageSearchRequest: …`

  - `query: str`

    Text query for full-text search

  - `agent_id: Optional[str]`

    Filter messages by agent ID

  - `conversation_id: Optional[str]`

    Filter messages by conversation ID

  - `end_date: Optional[datetime]`

    Filter messages created on or before this date

  - `limit: Optional[int]`

    Maximum number of results to return

  - `search_mode: Optional[Literal["vector", "fts", "hybrid"]]`

    Search mode to use

    - `"vector"`

    - `"fts"`

    - `"hybrid"`

  - `start_date: Optional[datetime]`

    Filter messages created after this date

### Message Search Result

- `class MessageSearchResult: …`

  Result from a message search operation with scoring details.

  - `embedded_text: str`

    The embedded content (LLM-friendly)

  - `message: InternalMessage`

    The raw message object

    - `id: str`

      The human-friendly ID of the Message

    - `role: MessageRole`

      The role of the participant.

      - `"assistant"`

      - `"user"`

      - `"tool"`

      - `"function"`

      - `"system"`

      - `"approval"`

      - `"summary"`

    - `agent_id: Optional[str]`

      The unique identifier of the agent.

    - `approval_request_id: Optional[str]`

      The id of the approval request if this message is associated with a tool call request.

    - `approvals: Optional[List[Approval]]`

      The list of approvals for this message.

      - `class ApprovalReturn: …`

        - `approve: bool`

          Whether the tool has been approved

        - `tool_call_id: str`

          The ID of the tool call that corresponds to this approval

        - `reason: Optional[str]`

          An optional explanation for the provided approval status

        - `type: Optional[Literal["approval"]]`

          The message type to be created.

          - `"approval"`

      - `class ApprovalLettaSchemasMessageToolReturnOutput: …`

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

          The status of the tool call

          - `"success"`

          - `"error"`

        - `func_response: Optional[Union[str, List[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1], null]]`

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

          - `str`

          - `List[ApprovalLettaSchemasMessageToolReturnOutputFuncResponseUnionMember1]`

            - `class TextContent: …`

              - `text: str`

                The text content of the message.

              - `signature: Optional[str]`

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

              - `type: Optional[Literal["text"]]`

                The type of the message.

                - `"text"`

            - `class ImageContent: …`

              - `source: Source`

                The source of the image.

                - `class SourceURLImage: …`

                  - `url: str`

                    The URL of the image.

                  - `type: Optional[Literal["url"]]`

                    The source type for the image.

                    - `"url"`

                - `class SourceBase64Image: …`

                  - `data: str`

                    The base64 encoded image data.

                  - `media_type: str`

                    The media type for the image.

                  - `detail: Optional[str]`

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

                  - `type: Optional[Literal["base64"]]`

                    The source type for the image.

                    - `"base64"`

                - `class SourceLettaImage: …`

                  - `file_id: str`

                    The unique identifier of the image file persisted in storage.

                  - `data: Optional[str]`

                    The base64 encoded image data.

                  - `detail: Optional[str]`

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

                  - `media_type: Optional[str]`

                    The media type for the image.

                  - `type: Optional[Literal["letta"]]`

                    The source type for the image.

                    - `"letta"`

              - `type: Optional[Literal["image"]]`

                The type of the message.

                - `"image"`

        - `stderr: Optional[List[str]]`

          Captured stderr from the tool invocation

        - `stdout: Optional[List[str]]`

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

        - `tool_call_id: Optional[object]`

          The ID for the tool call

    - `approve: Optional[bool]`

      Whether tool call is approved.

    - `batch_item_id: Optional[str]`

      The id of the LLMBatchItem that this message is associated with

    - `content: Optional[List[Content]]`

      The content of the message.

      - `class TextContent: …`

      - `class ImageContent: …`

      - `class ToolCallContent: …`

        - `id: str`

          A unique identifier for this specific tool call instance.

        - `input: Dict[str, object]`

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

        - `name: str`

          The name of the tool being called.

        - `signature: Optional[str]`

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

        - `type: Optional[Literal["tool_call"]]`

          Indicates this content represents a tool call event.

          - `"tool_call"`

      - `class ToolReturnContent: …`

        - `content: str`

          The content returned by the tool execution.

        - `is_error: bool`

          Indicates whether the tool execution resulted in an error.

        - `tool_call_id: str`

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

        - `type: Optional[Literal["tool_return"]]`

          Indicates this content represents a tool return event.

          - `"tool_return"`

      - `class ReasoningContent: …`

        Sent via the Anthropic Messages API

        - `is_native: bool`

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

        - `reasoning: str`

          The intermediate reasoning or thought process content.

        - `signature: Optional[str]`

          A unique identifier for this reasoning step.

        - `type: Optional[Literal["reasoning"]]`

          Indicates this is a reasoning/intermediate step.

          - `"reasoning"`

      - `class RedactedReasoningContent: …`

        Sent via the Anthropic Messages API

        - `data: str`

          The redacted or filtered intermediate reasoning content.

        - `type: Optional[Literal["redacted_reasoning"]]`

          Indicates this is a redacted thinking step.

          - `"redacted_reasoning"`

      - `class OmittedReasoningContent: …`

        A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)

        - `signature: Optional[str]`

          A unique identifier for this reasoning step.

        - `type: Optional[Literal["omitted_reasoning"]]`

          Indicates this is an omitted reasoning step.

          - `"omitted_reasoning"`

      - `class ContentSummarizedReasoningContent: …`

        The style of reasoning content returned by the OpenAI Responses API

        - `id: str`

          The unique identifier for this reasoning step.

        - `summary: List[ContentSummarizedReasoningContentSummary]`

          Summaries of the reasoning content.

          - `index: int`

            The index of the summary part.

          - `text: str`

            The text of the summary part.

        - `encrypted_content: Optional[str]`

          The encrypted reasoning content.

        - `type: Optional[Literal["summarized_reasoning"]]`

          Indicates this is a summarized reasoning step.

          - `"summarized_reasoning"`

    - `conversation_id: Optional[str]`

      The conversation this message belongs to

    - `created_at: Optional[datetime]`

      The timestamp when the object was created.

    - `created_by_id: Optional[str]`

      The id of the user that made this object.

    - `denial_reason: Optional[str]`

      The reason the tool call request was denied.

    - `group_id: Optional[str]`

      The multi-agent group that the message was sent in

    - `is_err: Optional[bool]`

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

    - `last_updated_by_id: Optional[str]`

      The id of the user that made this object.

    - `model: Optional[str]`

      The model used to make the function call.

    - `name: Optional[str]`

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

    - `otid: Optional[str]`

      The offline threading id associated with this message

    - `run_id: Optional[str]`

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

    - `sender_id: Optional[str]`

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

    - `step_id: Optional[str]`

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

    - `tool_call_id: Optional[str]`

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

    - `tool_calls: Optional[List[ToolCall]]`

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

      - `id: str`

      - `function: ToolCallFunction`

        The function that the model called.

        - `arguments: str`

        - `name: str`

      - `type: Literal["function"]`

        - `"function"`

    - `tool_returns: Optional[List[ToolReturn]]`

      Tool execution return information for prior tool calls

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

        The status of the tool call

        - `"success"`

        - `"error"`

      - `func_response: Optional[Union[str, List[ToolReturnFuncResponseUnionMember1], null]]`

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

        - `str`

        - `List[ToolReturnFuncResponseUnionMember1]`

          - `class TextContent: …`

          - `class ImageContent: …`

      - `stderr: Optional[List[str]]`

        Captured stderr from the tool invocation

      - `stdout: Optional[List[str]]`

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

      - `tool_call_id: Optional[object]`

        The ID for the tool call

    - `updated_at: Optional[datetime]`

      The timestamp when the object was last updated.

  - `rrf_score: float`

    Reciprocal Rank Fusion combined score

  - `fts_rank: Optional[int]`

    Full-text search rank position if FTS was used

  - `vector_rank: Optional[int]`

    Vector search rank position if vector search was used

### Message List Response

- `List[Message]`

  - `class SystemMessage: …`

    A message generated by the system. Never streamed back on a response, only used for cursor pagination.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (str): The message content sent by the system

    - `id: str`

    - `content: str`

      The message content sent by the system

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["system_message"]]`

      The type of the message.

      - `"system_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class UserMessage: …`

    A message sent by the user. Never streamed back on a response, only used for cursor pagination.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)

    - `id: str`

    - `content: Union[List[LettaUserMessageContentUnion], str]`

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

      - `List[LettaUserMessageContentUnion]`

        - `class TextContent: …`

          - `text: str`

            The text content of the message.

          - `signature: Optional[str]`

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

          - `type: Optional[Literal["text"]]`

            The type of the message.

            - `"text"`

        - `class ImageContent: …`

          - `source: Source`

            The source of the image.

            - `class SourceURLImage: …`

              - `url: str`

                The URL of the image.

              - `type: Optional[Literal["url"]]`

                The source type for the image.

                - `"url"`

            - `class SourceBase64Image: …`

              - `data: str`

                The base64 encoded image data.

              - `media_type: str`

                The media type for the image.

              - `detail: Optional[str]`

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

              - `type: Optional[Literal["base64"]]`

                The source type for the image.

                - `"base64"`

            - `class SourceLettaImage: …`

              - `file_id: str`

                The unique identifier of the image file persisted in storage.

              - `data: Optional[str]`

                The base64 encoded image data.

              - `detail: Optional[str]`

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

              - `media_type: Optional[str]`

                The media type for the image.

              - `type: Optional[Literal["letta"]]`

                The source type for the image.

                - `"letta"`

          - `type: Optional[Literal["image"]]`

            The type of the message.

            - `"image"`

      - `str`

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["user_message"]]`

      The type of the message.

      - `"user_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ReasoningMessage: …`

    Representation of an agent's internal reasoning.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning
    content was generated natively by a reasoner model or derived via prompting
    reasoning (str): The internal reasoning of the agent
    signature (Optional[str]): The model-generated signature of the reasoning step

    - `id: str`

    - `date: datetime`

    - `reasoning: str`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["reasoning_message"]]`

      The type of the message.

      - `"reasoning_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `signature: Optional[str]`

    - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]`

      - `"reasoner_model"`

      - `"non_reasoner_model"`

    - `step_id: Optional[str]`

  - `class HiddenReasoningMessage: …`

    Representation of an agent's internal reasoning where reasoning content
    has been hidden from the response.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    state (Literal["redacted", "omitted"]): Whether the reasoning
    content was redacted by the provider or simply omitted by the API
    hidden_reasoning (Optional[str]): The internal reasoning of the agent

    - `id: str`

    - `date: datetime`

    - `state: Literal["redacted", "omitted"]`

      - `"redacted"`

      - `"omitted"`

    - `hidden_reasoning: Optional[str]`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["hidden_reasoning_message"]]`

      The type of the message.

      - `"hidden_reasoning_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ToolCallMessage: …`

    A message representing a request to call a tool (generated by the LLM to trigger tool execution).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_call (Union[ToolCall, ToolCallDelta]): The tool call

    - `id: str`

    - `date: datetime`

    - `tool_call: ToolCall`

      - `class ToolCall: …`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

        - `arguments: Optional[str]`

        - `name: Optional[str]`

        - `tool_call_id: Optional[str]`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["tool_call_message"]]`

      The type of the message.

      - `"tool_call_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

    - `tool_calls: Optional[ToolCalls]`

      - `List[ToolCall]`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

  - `class ToolReturnMessage: …`

    A message representing the return value of a tool call (generated by Letta executing the requested tool).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_return (str): The return value of the tool (deprecated, use tool_returns)
    status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns)
    tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns)
    stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns)
    stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns)
    tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support

    - `id: str`

    - `date: datetime`

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

      - `"success"`

      - `"error"`

    - `tool_call_id: str`

    - `tool_return: str`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["tool_return_message"]]`

      The type of the message.

      - `"tool_return_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `stderr: Optional[List[str]]`

    - `stdout: Optional[List[str]]`

    - `step_id: Optional[str]`

    - `tool_returns: Optional[List[ToolReturn]]`

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

        - `"success"`

        - `"error"`

      - `tool_call_id: str`

      - `tool_return: Union[List[ToolReturnUnionMember0], str]`

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

        - `List[ToolReturnUnionMember0]`

          - `class TextContent: …`

          - `class ImageContent: …`

        - `str`

      - `stderr: Optional[List[str]]`

      - `stdout: Optional[List[str]]`

      - `type: Optional[Literal["tool"]]`

        The message type to be created.

        - `"tool"`

  - `class AssistantMessage: …`

    A message sent by the LLM in response to user input. Used in the LLM context.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)

    - `id: str`

    - `content: Union[List[LettaAssistantMessageContentUnion], str]`

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

      - `List[LettaAssistantMessageContentUnion]`

        - `text: str`

          The text content of the message.

        - `signature: Optional[str]`

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

        - `type: Optional[Literal["text"]]`

          The type of the message.

          - `"text"`

      - `str`

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["assistant_message"]]`

      The type of the message.

      - `"assistant_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ApprovalRequestMessage: …`

    A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_call (ToolCall): The tool call

    - `id: str`

    - `date: datetime`

    - `tool_call: ToolCall`

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

      - `class ToolCall: …`

      - `class ToolCallDelta: …`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["approval_request_message"]]`

      The type of the message.

      - `"approval_request_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

    - `tool_calls: Optional[ToolCalls]`

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

      - `List[ToolCall]`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

  - `class ApprovalResponseMessage: …`

    A message representing a response form the user indicating whether a tool has been approved to run.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    approve: (bool) Whether the tool has been approved
    approval_request_id: The ID of the approval request
    reason: (Optional[str]) An optional explanation for the provided approval status

    - `id: str`

    - `date: datetime`

    - `approval_request_id: Optional[str]`

      The message ID of the approval request

    - `approvals: Optional[List[Approval]]`

      The list of approval responses

      - `class ApprovalReturn: …`

        - `approve: bool`

          Whether the tool has been approved

        - `tool_call_id: str`

          The ID of the tool call that corresponds to this approval

        - `reason: Optional[str]`

          An optional explanation for the provided approval status

        - `type: Optional[Literal["approval"]]`

          The message type to be created.

          - `"approval"`

      - `class ToolReturn: …`

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

        - `tool_call_id: str`

        - `tool_return: Union[List[ToolReturnUnionMember0], str]`

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

        - `stderr: Optional[List[str]]`

        - `stdout: Optional[List[str]]`

        - `type: Optional[Literal["tool"]]`

          The message type to be created.

    - `approve: Optional[bool]`

      Whether the tool has been approved

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["approval_response_message"]]`

      The type of the message.

      - `"approval_response_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `reason: Optional[str]`

      An optional explanation for the provided approval status

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class SummaryMessage: …`

    A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.

    - `id: str`

    - `date: datetime`

    - `summary: str`

    - `compaction_stats: Optional[CompactionStats]`

      Statistics about a memory compaction operation.

      - `context_window: int`

        The model's context window size

      - `messages_count_after: int`

        Number of messages after compaction

      - `messages_count_before: int`

        Number of messages before compaction

      - `trigger: str`

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

      - `context_tokens_after: Optional[int]`

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

      - `context_tokens_before: Optional[int]`

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

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["summary_message"]]`

      - `"summary_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class EventMessage: …`

    A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.

    - `id: str`

    - `date: datetime`

    - `event_data: Dict[str, object]`

    - `event_type: Literal["compaction"]`

      - `"compaction"`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["event_message"]]`

      - `"event_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

### Message Retrieve Response

- `List[Message]`

  - `class SystemMessage: …`

    A message generated by the system. Never streamed back on a response, only used for cursor pagination.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (str): The message content sent by the system

    - `id: str`

    - `content: str`

      The message content sent by the system

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["system_message"]]`

      The type of the message.

      - `"system_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class UserMessage: …`

    A message sent by the user. Never streamed back on a response, only used for cursor pagination.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)

    - `id: str`

    - `content: Union[List[LettaUserMessageContentUnion], str]`

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

      - `List[LettaUserMessageContentUnion]`

        - `class TextContent: …`

          - `text: str`

            The text content of the message.

          - `signature: Optional[str]`

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

          - `type: Optional[Literal["text"]]`

            The type of the message.

            - `"text"`

        - `class ImageContent: …`

          - `source: Source`

            The source of the image.

            - `class SourceURLImage: …`

              - `url: str`

                The URL of the image.

              - `type: Optional[Literal["url"]]`

                The source type for the image.

                - `"url"`

            - `class SourceBase64Image: …`

              - `data: str`

                The base64 encoded image data.

              - `media_type: str`

                The media type for the image.

              - `detail: Optional[str]`

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

              - `type: Optional[Literal["base64"]]`

                The source type for the image.

                - `"base64"`

            - `class SourceLettaImage: …`

              - `file_id: str`

                The unique identifier of the image file persisted in storage.

              - `data: Optional[str]`

                The base64 encoded image data.

              - `detail: Optional[str]`

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

              - `media_type: Optional[str]`

                The media type for the image.

              - `type: Optional[Literal["letta"]]`

                The source type for the image.

                - `"letta"`

          - `type: Optional[Literal["image"]]`

            The type of the message.

            - `"image"`

      - `str`

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["user_message"]]`

      The type of the message.

      - `"user_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ReasoningMessage: …`

    Representation of an agent's internal reasoning.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning
    content was generated natively by a reasoner model or derived via prompting
    reasoning (str): The internal reasoning of the agent
    signature (Optional[str]): The model-generated signature of the reasoning step

    - `id: str`

    - `date: datetime`

    - `reasoning: str`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["reasoning_message"]]`

      The type of the message.

      - `"reasoning_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `signature: Optional[str]`

    - `source: Optional[Literal["reasoner_model", "non_reasoner_model"]]`

      - `"reasoner_model"`

      - `"non_reasoner_model"`

    - `step_id: Optional[str]`

  - `class HiddenReasoningMessage: …`

    Representation of an agent's internal reasoning where reasoning content
    has been hidden from the response.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    state (Literal["redacted", "omitted"]): Whether the reasoning
    content was redacted by the provider or simply omitted by the API
    hidden_reasoning (Optional[str]): The internal reasoning of the agent

    - `id: str`

    - `date: datetime`

    - `state: Literal["redacted", "omitted"]`

      - `"redacted"`

      - `"omitted"`

    - `hidden_reasoning: Optional[str]`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["hidden_reasoning_message"]]`

      The type of the message.

      - `"hidden_reasoning_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ToolCallMessage: …`

    A message representing a request to call a tool (generated by the LLM to trigger tool execution).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_call (Union[ToolCall, ToolCallDelta]): The tool call

    - `id: str`

    - `date: datetime`

    - `tool_call: ToolCall`

      - `class ToolCall: …`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

        - `arguments: Optional[str]`

        - `name: Optional[str]`

        - `tool_call_id: Optional[str]`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["tool_call_message"]]`

      The type of the message.

      - `"tool_call_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

    - `tool_calls: Optional[ToolCalls]`

      - `List[ToolCall]`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

  - `class ToolReturnMessage: …`

    A message representing the return value of a tool call (generated by Letta executing the requested tool).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_return (str): The return value of the tool (deprecated, use tool_returns)
    status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns)
    tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns)
    stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns)
    stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns)
    tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support

    - `id: str`

    - `date: datetime`

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

      - `"success"`

      - `"error"`

    - `tool_call_id: str`

    - `tool_return: str`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["tool_return_message"]]`

      The type of the message.

      - `"tool_return_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `stderr: Optional[List[str]]`

    - `stdout: Optional[List[str]]`

    - `step_id: Optional[str]`

    - `tool_returns: Optional[List[ToolReturn]]`

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

        - `"success"`

        - `"error"`

      - `tool_call_id: str`

      - `tool_return: Union[List[ToolReturnUnionMember0], str]`

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

        - `List[ToolReturnUnionMember0]`

          - `class TextContent: …`

          - `class ImageContent: …`

        - `str`

      - `stderr: Optional[List[str]]`

      - `stdout: Optional[List[str]]`

      - `type: Optional[Literal["tool"]]`

        The message type to be created.

        - `"tool"`

  - `class AssistantMessage: …`

    A message sent by the LLM in response to user input. Used in the LLM context.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)

    - `id: str`

    - `content: Union[List[LettaAssistantMessageContentUnion], str]`

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

      - `List[LettaAssistantMessageContentUnion]`

        - `text: str`

          The text content of the message.

        - `signature: Optional[str]`

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

        - `type: Optional[Literal["text"]]`

          The type of the message.

          - `"text"`

      - `str`

    - `date: datetime`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["assistant_message"]]`

      The type of the message.

      - `"assistant_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class ApprovalRequestMessage: …`

    A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    tool_call (ToolCall): The tool call

    - `id: str`

    - `date: datetime`

    - `tool_call: ToolCall`

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

      - `class ToolCall: …`

      - `class ToolCallDelta: …`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["approval_request_message"]]`

      The type of the message.

      - `"approval_request_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

    - `tool_calls: Optional[ToolCalls]`

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

      - `List[ToolCall]`

        - `arguments: str`

        - `name: str`

        - `tool_call_id: str`

      - `class ToolCallDelta: …`

  - `class ApprovalResponseMessage: …`

    A message representing a response form the user indicating whether a tool has been approved to run.

    Args:
    id (str): The ID of the message
    date (datetime): The date the message was created in ISO format
    name (Optional[str]): The name of the sender of the message
    approve: (bool) Whether the tool has been approved
    approval_request_id: The ID of the approval request
    reason: (Optional[str]) An optional explanation for the provided approval status

    - `id: str`

    - `date: datetime`

    - `approval_request_id: Optional[str]`

      The message ID of the approval request

    - `approvals: Optional[List[Approval]]`

      The list of approval responses

      - `class ApprovalReturn: …`

        - `approve: bool`

          Whether the tool has been approved

        - `tool_call_id: str`

          The ID of the tool call that corresponds to this approval

        - `reason: Optional[str]`

          An optional explanation for the provided approval status

        - `type: Optional[Literal["approval"]]`

          The message type to be created.

          - `"approval"`

      - `class ToolReturn: …`

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

        - `tool_call_id: str`

        - `tool_return: Union[List[ToolReturnUnionMember0], str]`

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

        - `stderr: Optional[List[str]]`

        - `stdout: Optional[List[str]]`

        - `type: Optional[Literal["tool"]]`

          The message type to be created.

    - `approve: Optional[bool]`

      Whether the tool has been approved

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["approval_response_message"]]`

      The type of the message.

      - `"approval_response_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `reason: Optional[str]`

      An optional explanation for the provided approval status

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class SummaryMessage: …`

    A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.

    - `id: str`

    - `date: datetime`

    - `summary: str`

    - `compaction_stats: Optional[CompactionStats]`

      Statistics about a memory compaction operation.

      - `context_window: int`

        The model's context window size

      - `messages_count_after: int`

        Number of messages after compaction

      - `messages_count_before: int`

        Number of messages before compaction

      - `trigger: str`

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

      - `context_tokens_after: Optional[int]`

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

      - `context_tokens_before: Optional[int]`

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

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["summary_message"]]`

      - `"summary_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

  - `class EventMessage: …`

    A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.

    - `id: str`

    - `date: datetime`

    - `event_data: Dict[str, object]`

    - `event_type: Literal["compaction"]`

      - `"compaction"`

    - `is_err: Optional[bool]`

    - `message_type: Optional[Literal["event_message"]]`

      - `"event_message"`

    - `name: Optional[str]`

    - `otid: Optional[str]`

      The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

    - `run_id: Optional[str]`

    - `sender_id: Optional[str]`

    - `seq_id: Optional[int]`

    - `step_id: Optional[str]`

### Message Search Response

- `List[MessageSearchResponseItem]`

  - `class MessageSearchResponseItemSystemMessageListResult: …`

    System message list result with agent context.

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

    - `content: str`

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

    - `created_at: datetime`

      The time the message was created in ISO format.

    - `message_id: str`

      The unique identifier of the message.

    - `agent_id: Optional[str]`

      The unique identifier of the agent that owns the message.

    - `conversation_id: Optional[str]`

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

    - `message_type: Optional[Literal["system_message"]]`

      - `"system_message"`

  - `class MessageSearchResponseItemUserMessageListResult: …`

    User message list result with agent context.

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

    - `content: Union[List[LettaUserMessageContentUnion], str]`

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

      - `List[LettaUserMessageContentUnion]`

        - `class TextContent: …`

          - `text: str`

            The text content of the message.

          - `signature: Optional[str]`

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

          - `type: Optional[Literal["text"]]`

            The type of the message.

            - `"text"`

        - `class ImageContent: …`

          - `source: Source`

            The source of the image.

            - `class SourceURLImage: …`

              - `url: str`

                The URL of the image.

              - `type: Optional[Literal["url"]]`

                The source type for the image.

                - `"url"`

            - `class SourceBase64Image: …`

              - `data: str`

                The base64 encoded image data.

              - `media_type: str`

                The media type for the image.

              - `detail: Optional[str]`

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

              - `type: Optional[Literal["base64"]]`

                The source type for the image.

                - `"base64"`

            - `class SourceLettaImage: …`

              - `file_id: str`

                The unique identifier of the image file persisted in storage.

              - `data: Optional[str]`

                The base64 encoded image data.

              - `detail: Optional[str]`

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

              - `media_type: Optional[str]`

                The media type for the image.

              - `type: Optional[Literal["letta"]]`

                The source type for the image.

                - `"letta"`

          - `type: Optional[Literal["image"]]`

            The type of the message.

            - `"image"`

      - `str`

    - `created_at: datetime`

      The time the message was created in ISO format.

    - `message_id: str`

      The unique identifier of the message.

    - `agent_id: Optional[str]`

      The unique identifier of the agent that owns the message.

    - `conversation_id: Optional[str]`

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

    - `message_type: Optional[Literal["user_message"]]`

      - `"user_message"`

  - `class MessageSearchResponseItemReasoningMessageListResult: …`

    Reasoning message list result with agent context.

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

    - `created_at: datetime`

      The time the message was created in ISO format.

    - `message_id: str`

      The unique identifier of the message.

    - `reasoning: str`

    - `agent_id: Optional[str]`

      The unique identifier of the agent that owns the message.

    - `conversation_id: Optional[str]`

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

    - `message_type: Optional[Literal["reasoning_message"]]`

      - `"reasoning_message"`

  - `class MessageSearchResponseItemAssistantMessageListResult: …`

    Assistant message list result with agent context.

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

    - `content: Union[List[LettaAssistantMessageContentUnion], str]`

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

      - `List[LettaAssistantMessageContentUnion]`

        - `text: str`

          The text content of the message.

        - `signature: Optional[str]`

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

        - `type: Optional[Literal["text"]]`

          The type of the message.

          - `"text"`

      - `str`

    - `created_at: datetime`

      The time the message was created in ISO format.

    - `message_id: str`

      The unique identifier of the message.

    - `agent_id: Optional[str]`

      The unique identifier of the agent that owns the message.

    - `conversation_id: Optional[str]`

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

    - `message_type: Optional[Literal["assistant_message"]]`

      - `"assistant_message"`