List Messages

List messages for a task in Vercel AI SDK UIMessage format.

This endpoint returns messages transformed from raw SDK events into a normalized UIMessage format suitable for frontend consumption.

Features:

Tool merging: tool_use and tool_result are combined into single tool parts
Complete-units pagination: Never splits tool request/result pairs across pages
Runtime transformation: Raw SDK messages are transformed on-demand

Args: task_id: The task ID to filter messages by limit: Maximum number of complete messages to return (default: 50) cursor: Opaque cursor string for pagination direction: Pagination direction - “older” (default) or “newer” parent_tool_use_id: Filter messages by parent tool use ID (for subagent context)

Returns: ListMessagesV2Response with UIMessages and pagination info

GET

messages

List Messages (v2 - UIMessage format)

curl --request GET \
  --url https://api.example.com/v2/messages

{
  "data": [
    {
      "id": "<string>",
      "parts": [
        {
          "text": "<string>",
          "type": "text"
        }
      ],
      "createdAt": "<string>",
      "metadata": {
        "costUsd": 123,
        "durationMs": 123,
        "model": "<string>",
        "parentToolUseId": "<string>",
        "usage": {
          "inputTokens": 123,
          "outputTokens": 123,
          "totalTokens": 123
        }
      }
    }
  ],
  "hasMore": false,
  "nextCursor": "<string>"
}

Query Parameters

limit

integer

default:50

cursor

string | null

direction

enum<string>

default:older

Available options:

older,

newer

parent_tool_use_id

string | null

task_id

string

required

The task ID

Response

Successful Response

Response for list messages v2 endpoint.

data

UIMessage · object[]

required

List of UIMessages

Show child attributes

hasMore

boolean

default:false

Whether there are more messages to fetch

nextCursor

string | null

Cursor for fetching the next page

Get MessageGet a single message by ID in UIMessage format. Returns the transformed UIMessage or null if not found.

List Messages (v2 - UIMessage format)

curl --request GET \
  --url https://api.example.com/v2/messages

{
  "data": [
    {
      "id": "<string>",
      "parts": [
        {
          "text": "<string>",
          "type": "text"
        }
      ],
      "createdAt": "<string>",
      "metadata": {
        "costUsd": 123,
        "durationMs": 123,
        "model": "<string>",
        "parentToolUseId": "<string>",
        "usage": {
          "inputTokens": 123,
          "outputTokens": 123,
          "totalTokens": 123
        }
      }
    }
  ],
  "hasMore": false,
  "nextCursor": "<string>"
}