## List Messages

`agents.messages.list(stragent_id, MessageListParams**kwargs)  -> SyncArrayPage[Message]`

**get** `/v1/agents/{agent_id}/messages`

Retrieve message history for an agent.

### Parameters

- `agent_id: str`

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

- `after: Optional[str]`

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

- `assistant_message_tool_kwarg: Optional[str]`

  The name of the message argument.

- `assistant_message_tool_name: Optional[str]`

  The name of the designated message tool.

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

- `group_id: Optional[str]`

  Group ID to filter messages by.

- `include_err: Optional[bool]`

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

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

- `order_by: Optional[Literal["created_at"]]`

  Field to sort by

  - `"created_at"`

- `use_assistant_message: Optional[bool]`

  Whether to use assistant messages

### Returns

- `Message`

  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

  - `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
)
page = client.agents.messages.list(
    agent_id="agent-123e4567-e89b-42d3-8456-426614174000",
)
page = page.items[0]
print(page)
```

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