## List Messages Paginated

`messages.list_paginated(MessageListPaginatedParams**kwargs)  -> MessageListPaginatedResponse`

**get** `/messages/paginated`

List messages for a task with cursor-based pagination.

This endpoint is designed for infinite scroll UIs where new messages may arrive
while paginating through older ones.

Args:
task_id: The task ID to filter messages by
limit: Maximum number of messages to return (default: 50)
cursor: Opaque cursor string for pagination. Pass the `next_cursor` from
a previous response to get the next page.
direction: Pagination direction - "older" to get older messages (default),
"newer" to get newer messages.

Returns:
PaginatedMessagesResponse with:
- data: List of messages (newest first when direction="older")
- next_cursor: Cursor for fetching the next page (null if no more pages)
- has_more: Whether there are more messages to fetch

Example:
First request: GET /messages/paginated?task_id=xxx&limit=50
Next page: GET /messages/paginated?task_id=xxx&limit=50&cursor=<next_cursor>

### Parameters

- `task_id: str`

  The task ID

- `cursor: Optional[str]`

- `direction: Optional[Literal["older", "newer"]]`

  - `"older"`

  - `"newer"`

- `filters: Optional[str]`

  JSON-encoded array of TaskMessageEntityFilter objects.

  Schema: {
  "$defs": {
  "DataContentEntityOptional": {
  "properties": {
  "type": {
  "anyOf": [
  {
  "const": "data",
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The type of the message, in this case `data`.",
  "title": "Type"
  },
  "author": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageAuthor"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`."
  },
  "style": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageStyle"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The style of the message. This is used by the client to determine how to display the message."
  },
  "data": {
  "anyOf": [
  {
  "additionalProperties": true,
  "type": "object"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The contents of the data message.",
  "title": "Data"
  }
  },
  "title": "DataContentEntityOptional",
  "type": "object"
  },
  "FileAttachmentEntity": {
  "description": "Represents a file attachment in messages.",
  "properties": {
  "file_id": {
  "description": "The unique ID of the attached file",
  "title": "File Id",
  "type": "string"
  },
  "name": {
  "description": "The name of the file",
  "title": "Name",
  "type": "string"
  },
  "size": {
  "description": "The size of the file in bytes",
  "title": "Size",
  "type": "integer"
  },
  "type": {
  "description": "The MIME type or content type of the file",
  "title": "Type",
  "type": "string"
  }
  },
  "required": [
  "file_id",
  "name",
  "size",
  "type"
  ],
  "title": "FileAttachmentEntity",
  "type": "object"
  },
  "MessageAuthor": {
  "enum": [
  "user",
  "agent"
  ],
  "title": "MessageAuthor",
  "type": "string"
  },
  "MessageStyle": {
  "enum": [
  "static",
  "active"
  ],
  "title": "MessageStyle",
  "type": "string"
  },
  "ReasoningContentEntityOptional": {
  "properties": {
  "type": {
  "anyOf": [
  {
  "const": "reasoning",
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The type of the message, in this case `reasoning`.",
  "title": "Type"
  },
  "author": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageAuthor"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`."
  },
  "style": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageStyle"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The style of the message. This is used by the client to determine how to display the message."
  },
  "summary": {
  "anyOf": [
  {
  "items": {
  "type": "string"
  },
  "type": "array"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "A list of short reasoning summaries",
  "title": "Summary"
  },
  "content": {
  "anyOf": [
  {
  "items": {
  "type": "string"
  },
  "type": "array"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The reasoning content or chain-of-thought text",
  "title": "Content"
  }
  },
  "title": "ReasoningContentEntityOptional",
  "type": "object"
  },
  "TextContentEntityOptional": {
  "properties": {
  "type": {
  "anyOf": [
  {
  "const": "text",
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The type of the message, in this case `text`.",
  "title": "Type"
  },
  "author": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageAuthor"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`."
  },
  "style": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageStyle"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The style of the message. This is used by the client to determine how to display the message."
  },
  "format": {
  "anyOf": [
  {
  "$ref": "#/$defs/TextFormat"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The format of the message. This is used by the client to determine how to display the message."
  },
  "content": {
  "anyOf": [
  {
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The contents of the text message.",
  "title": "Content"
  },
  "attachments": {
  "anyOf": [
  {
  "items": {
  "$ref": "#/$defs/FileAttachmentEntity"
  },
  "type": "array"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "Optional list of file attachments with structured metadata.",
  "title": "Attachments"
  }
  },
  "title": "TextContentEntityOptional",
  "type": "object"
  },
  "TextFormat": {
  "enum": [
  "markdown",
  "plain",
  "code"
  ],
  "title": "TextFormat",
  "type": "string"
  },
  "ToolRequestContentEntityOptional": {
  "properties": {
  "type": {
  "anyOf": [
  {
  "const": "tool_request",
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The type of the message, in this case `tool_request`.",
  "title": "Type"
  },
  "author": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageAuthor"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`."
  },
  "style": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageStyle"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The style of the message. This is used by the client to determine how to display the message."
  },
  "tool_call_id": {
  "anyOf": [
  {
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The ID of the tool call that is being requested.",
  "title": "Tool Call Id"
  },
  "name": {
  "anyOf": [
  {
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The name of the tool that is being requested.",
  "title": "Name"
  },
  "arguments": {
  "anyOf": [
  {
  "additionalProperties": true,
  "type": "object"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The arguments to the tool.",
  "title": "Arguments"
  }
  },
  "title": "ToolRequestContentEntityOptional",
  "type": "object"
  },
  "ToolResponseContentEntityOptional": {
  "properties": {
  "type": {
  "anyOf": [
  {
  "const": "tool_response",
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The type of the message, in this case `tool_response`.",
  "title": "Type"
  },
  "author": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageAuthor"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`."
  },
  "style": {
  "anyOf": [
  {
  "$ref": "#/$defs/MessageStyle"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The style of the message. This is used by the client to determine how to display the message."
  },
  "tool_call_id": {
  "anyOf": [
  {
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The ID of the tool call that is being responded to.",
  "title": "Tool Call Id"
  },
  "name": {
  "anyOf": [
  {
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The name of the tool that is being responded to.",
  "title": "Name"
  },
  "content": {
  "anyOf": [
  {},
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "The result of the tool.",
  "title": "Content"
  },
  "is_error": {
  "anyOf": [
  {
  "type": "boolean"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.",
  "title": "Is Error"
  }
  },
  "title": "ToolResponseContentEntityOptional",
  "type": "object"
  }
  },
  "description": "Filter model for TaskMessage - all fields optional for flexible filtering.\n\nThe `exclude` field determines whether this filter is inclusionary or exclusionary.\nWhen multiple filters are provided:\n- Inclusionary filters (exclude=False) are OR'd together\n- Exclusionary filters (exclude=True) are OR'd together and negated with $nor\n- The two groups are AND'd: (include1 OR include2) AND NOT (exclude1 OR exclude2)",
  "properties": {
  "content": {
  "anyOf": [
  {
  "$ref": "#/$defs/ToolRequestContentEntityOptional"
  },
  {
  "$ref": "#/$defs/DataContentEntityOptional"
  },
  {
  "$ref": "#/$defs/TextContentEntityOptional"
  },
  {
  "$ref": "#/$defs/ToolResponseContentEntityOptional"
  },
  {
  "$ref": "#/$defs/ReasoningContentEntityOptional"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "Filter by message content",
  "title": "Content"
  },
  "streaming_status": {
  "anyOf": [
  {
  "enum": [
  "IN_PROGRESS",
  "DONE"
  ],
  "type": "string"
  },
  {
  "type": "null"
  }
  ],
  "default": null,
  "description": "Filter by streaming status",
  "title": "Streaming Status"
  },
  "exclude": {
  "default": false,
  "description": "If true, this filter excludes matching messages",
  "title": "Exclude",
  "type": "boolean"
  }
  },
  "title": "TaskMessageEntityFilter",
  "type": "object"
  }

  Each filter can include:

  - `content`: Filter by message content (type, author, data fields)
  - `streaming_status`: Filter by status ("IN_PROGRESS" or "DONE")
  - `exclude`: If true, excludes matching messages (default: false)

  Multiple filters are combined: inclusionary filters (exclude=false) are OR'd together,
  exclusionary filters (exclude=true) are OR'd and negated, then both groups are AND'd.

- `limit: Optional[int]`

### Returns

- `class MessageListPaginatedResponse: …`

  Response with cursor pagination metadata.

  - `data: List[TaskMessage]`

    List of messages

    - `content: TaskMessageContent`

      The content of the message. This content is not OpenAI compatible. These are messages that are meant to be displayed to the user.

      - `class TextContent: …`

        - `author: MessageAuthor`

          The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`.

          - `"user"`

          - `"agent"`

        - `content: str`

          The contents of the text message.

        - `attachments: Optional[List[Attachment]]`

          Optional list of file attachments with structured metadata.

          - `file_id: str`

            The unique ID of the attached file

          - `name: str`

            The name of the file

          - `size: int`

            The size of the file in bytes

          - `type: str`

            The MIME type or content type of the file

        - `format: Optional[TextFormat]`

          The format of the message. This is used by the client to determine how to display the message.

          - `"markdown"`

          - `"plain"`

          - `"code"`

        - `style: Optional[MessageStyle]`

          The style of the message. This is used by the client to determine how to display the message.

          - `"static"`

          - `"active"`

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

          The type of the message, in this case `text`.

          - `"text"`

      - `class ReasoningContent: …`

        - `author: MessageAuthor`

          The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`.

        - `summary: List[str]`

          A list of short reasoning summaries

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

          The reasoning content or chain-of-thought text

        - `style: Optional[MessageStyle]`

          The style of the message. This is used by the client to determine how to display the message.

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

          The type of the message, in this case `reasoning`.

          - `"reasoning"`

      - `class DataContent: …`

        - `author: MessageAuthor`

          The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`.

        - `data: Dict[str, object]`

          The contents of the data message.

        - `style: Optional[MessageStyle]`

          The style of the message. This is used by the client to determine how to display the message.

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

          The type of the message, in this case `data`.

          - `"data"`

      - `class ToolRequestContent: …`

        - `arguments: Dict[str, object]`

          The arguments to the tool.

        - `author: MessageAuthor`

          The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`.

        - `name: str`

          The name of the tool that is being requested.

        - `tool_call_id: str`

          The ID of the tool call that is being requested.

        - `style: Optional[MessageStyle]`

          The style of the message. This is used by the client to determine how to display the message.

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

          The type of the message, in this case `tool_request`.

          - `"tool_request"`

      - `class ToolResponseContent: …`

        - `author: MessageAuthor`

          The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`.

        - `content: object`

          The result of the tool.

        - `name: str`

          The name of the tool that is being responded to.

        - `tool_call_id: str`

          The ID of the tool call that is being responded to.

        - `is_error: Optional[bool]`

          Whether the tool call resulted in an error. `None` when the harness does not report a status.

        - `style: Optional[MessageStyle]`

          The style of the message. This is used by the client to determine how to display the message.

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

          The type of the message, in this case `tool_response`.

          - `"tool_response"`

    - `task_id: str`

      ID of the task this message belongs to

    - `id: Optional[str]`

      The task message's unique id

    - `created_at: Optional[datetime]`

      The timestamp when the message was created

    - `streaming_status: Optional[Literal["IN_PROGRESS", "DONE"]]`

      - `"IN_PROGRESS"`

      - `"DONE"`

    - `updated_at: Optional[datetime]`

      The timestamp when the message was last updated

  - `has_more: Optional[bool]`

    Whether there are more messages to fetch

  - `next_cursor: Optional[str]`

    Cursor for fetching the next page of older messages

### Example

```python
import os
from agentex import Agentex

client = Agentex(
    api_key=os.environ.get("AGENTEX_SDK_API_KEY"),  # This is the default and can be omitted
)
response = client.messages.list_paginated(
    task_id="task_id",
)
print(response.data)
```

#### Response

```json
{
  "data": [
    {
      "content": {
        "author": "user",
        "content": "content",
        "attachments": [
          {
            "file_id": "file_id",
            "name": "name",
            "size": 0,
            "type": "type"
          }
        ],
        "format": "markdown",
        "style": "static",
        "type": "text"
      },
      "task_id": "task_id",
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "streaming_status": "IN_PROGRESS",
      "updated_at": "2019-12-27T18:11:19.117Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next_cursor"
}
```