---
title: "List Messages (v2 - UIMessage format)"
method: GET
path: "/v2/messages"
tags: ["Messages v2"]
---

# List Messages (v2 - UIMessage format)

`GET /v2/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

## Query parameters

- `limit` integer
- `cursor` string, nullable
- `direction` 'older' | 'newer'
- `parent_tool_use_id` string, nullable
- `task_id` string, required — The task ID

## Response `200`

Successful Response

- ListMessagesV2Response — Response for list messages v2 endpoint.
  - `data` UIMessage[], required — List of UIMessages
    - `createdAt` string, nullable — ISO timestamp when created
    - `id` string, required — Unique message ID
    - `metadata` UIMessageMetadata — Metadata for a UIMessage.
      - `costUsd` number, nullable — Cost in USD for this message
      - `durationMs` integer, nullable — Duration in milliseconds
      - `model` string, nullable — Model used to generate message
      - `parentToolUseId` string, nullable — Parent tool use ID for subagent context
      - `usage` Usage — Token usage statistics.
        - `inputTokens` integer, required — Input tokens used
        - `outputTokens` integer, required — Output tokens used
        - `totalTokens` integer, nullable — Total tokens (input + output)
    - `parts` UIMessagePartWrapper[], required — Content parts of the message
      - union — Wrapper for UIMessagePart union for proper serialization.
        - TextPart — Text content part.
          - `text` string, required — The text content
          - `type` 'text' — Part type discriminator
        - ReasoningPart — Reasoning/thinking content part (Claude's extended thinking).
          - `providerMetadata` object, nullable — Provider-specific metadata (e.g., Claude's thinking.signature)
          - `text` string, required — The reasoning text content
          - `type` 'reasoning' — Part type discriminator
        - ToolPart — Tool invocation and result part.
          - `errorText` string, nullable — Error message if tool failed
          - `input` object, required — Input arguments for the tool
          - `output` unknown
          - `state` 'input-streaming' | 'input-available' | 'output-available' | 'output-error', required — State of a tool part.
          - `toolCallId` string, required — Unique ID for this tool call
          - `toolName` string, required — Name of the tool
          - `type` 'tool' — Part type discriminator
        - SourceUrlPart — Source URL reference part.
          - `sourceId` string, required — Unique source ID
          - `title` string, nullable — Title of the source
          - `type` 'source-url' — Part type discriminator
          - `url` string, required — URL of the source
        - FilePart — File attachment part.
          - `mediaType` string, required — MIME type of the file
          - `type` 'file' — Part type discriminator
          - `url` string, required — URL to the file
        - DataPart — Generic data part for unknown/passthrough content.
          - `data` unknown, required
          - `type` 'data' — Part type discriminator
        - ErrorPart — Error part for transformation failures.
          - `error` string, required — Error message
          - `rawContent` unknown
          - `type` 'error' — Part type discriminator
    - `role` 'system' | 'user' | 'assistant', required — Role of the message author.
  - `hasMore` boolean — Whether there are more messages to fetch
  - `nextCursor` string, nullable — Cursor for fetching the next page

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/terminaluse/apis/sb0-api.md) · [All operations](https://skmtc.net/terminaluse/apis/sb0-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/terminaluse/sb0-api/revisions/f24a474dc415/schema)