---
title: "List Messages Paginated"
method: GET
path: "/messages/paginated"
tags: ["Messages"]
---

# List Messages Paginated

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

## Query parameters

- `limit` integer
- `cursor` string, nullable
- `direction` 'older' | 'newer'
- `filters` string, nullable — 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.
- `task_id` string, required — The task ID

## Response `200`

Successful Response

- PaginatedMessagesResponse — Response with cursor pagination metadata.
  - `data` TaskMessage[], required — List of messages
    - `id` string, nullable — The task message's unique id
    - `task_id` string, required — ID of the task this message belongs to
    - `content` union, required
      - TextContent
        - `type` 'text' — The type of the message, in this case `text`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `format` 'markdown' | 'plain' | 'code'
        - `content` string, required — The contents of the text message.
        - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata.
          - `file_id` string, required — The unique ID of the attached file
          - `name` string, required — The name of the file
          - `size` integer, required — The size of the file in bytes
          - `type` string, required — The MIME type or content type of the file
      - ReasoningContent
        - `type` 'reasoning' — The type of the message, in this case `reasoning`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `summary` string[], required — A list of short reasoning summaries
        - `content` string[], nullable — The reasoning content or chain-of-thought text
      - DataContent
        - `type` 'data' — The type of the message, in this case `data`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `data` object, required — The contents of the data message.
      - ToolRequestContent
        - `type` 'tool_request' — The type of the message, in this case `tool_request`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `tool_call_id` string, required — The ID of the tool call that is being requested.
        - `name` string, required — The name of the tool that is being requested.
        - `arguments` object, required — The arguments to the tool.
      - ToolResponseContent
        - `type` 'tool_response' — The type of the message, in this case `tool_response`.
        - `author` 'user' | 'agent', required
        - `style` 'static' | 'active'
        - `tool_call_id` string, required — The ID of the tool call that is being responded to.
        - `name` string, required — The name of the tool that is being responded to.
        - `content` unknown, required
        - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status.
    - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable
    - `created_at` string, date-time, nullable — The timestamp when the message was created
    - `updated_at` string, date-time, nullable — The timestamp when the message was last updated
  - `next_cursor` string, nullable — Cursor for fetching the next page of older messages
  - `has_more` boolean — Whether there are more messages to fetch

## Other responses

- `422` — Validation Error

## Changes

> 55 revisions in range; 4 could not be searched.

- **2026-07-10** `fbecbdbd7dc5` — 1 info
  - added the optional property `data/items/content/oneOf[subschema #5: ToolResponseContent]/is_error` to the response with the `200` status
- **2026-06-23** `94d73d46952b` — 1 warning
  - removed the optional property `data/items/content/oneOf[subschema #5: ToolResponseContent]/is_error` from the response with the `200` status
- **2026-06-22** `28b893025743` — 1 info
  - added the optional property `data/items/content/oneOf[subschema #5: ToolResponseContent]/is_error` to the response with the `200` status

[Change history](https://skmtc.dev/scaleapi/apis/agentex-api/changes/messages/paginated/get.md)

---

[API](https://skmtc.dev/scaleapi/apis/agentex-api.md) · [All operations](https://skmtc.dev/scaleapi/apis/agentex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scaleapi/agentex-api/revisions/1e0aaafd5780/schema)