Skip to content

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>

ParametersExpand Collapse
task_id: str

The task ID

cursor: Optional[str]
direction: Optional[Literal["older", "newer"]]
One of the following:
"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]
ReturnsExpand Collapse
class MessageListPaginatedResponse: …

Response with cursor pagination metadata.

data: List[TaskMessage]

List of messages

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

One of the following:
class TextContent: …

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

One of the following:
"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.

One of the following:
"markdown"
"plain"
"code"
style: Optional[MessageStyle]

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

One of the following:
"static"
"active"
type: Optional[Literal["text"]]

The type of the message, in this case text.

class ReasoningContent: …

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

One of the following:
"user"
"agent"
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.

One of the following:
"static"
"active"
type: Optional[Literal["reasoning"]]

The type of the message, in this case reasoning.

class DataContent: …

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

One of the following:
"user"
"agent"
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.

One of the following:
"static"
"active"
type: Optional[Literal["data"]]

The type of the message, in this case data.

class ToolRequestContent: …
arguments: Dict[str, object]

The arguments to the tool.

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

One of the following:
"user"
"agent"
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.

One of the following:
"static"
"active"
type: Optional[Literal["tool_request"]]

The type of the message, in this case tool_request.

class ToolResponseContent: …

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

One of the following:
"user"
"agent"
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.

One of the following:
"static"
"active"
type: Optional[Literal["tool_response"]]

The type of the message, in this case 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

formatdate-time
streaming_status: Optional[Literal["IN_PROGRESS", "DONE"]]
One of the following:
"IN_PROGRESS"
"DONE"
updated_at: Optional[datetime]

The timestamp when the message was last updated

formatdate-time
has_more: Optional[bool]

Whether there are more messages to fetch

next_cursor: Optional[str]

Cursor for fetching the next page of older messages

List Messages Paginated

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)
{
  "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"
}
Returns Examples
{
  "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"
}