---
title: "List Session Messages"
method: GET
path: "/v1/agent_sessions/{session_id}/messages"
tags: ["chat"]
---

# List Session Messages

`GET /v1/agent_sessions/{session_id}/messages`

Page through an owned session's persisted transcript, oldest first.

## Path parameters

- `session_id` string, required

## Query parameters

- `cursor` string, nullable — Opaque pagination cursor.
- `limit` integer

## Response `200`

Successful Response

- ListAgentSessionMessagesResponseBody
  - `data` PhoenixUIMessage[], required
    - `id` string, required
    - `role` 'system' | 'user' | 'assistant', required
    - `metadata` MessageMetadata — ``UIMessage.metadata`` as a registry of namespaces.
      - `phoenix` union
        - PhoenixAssistantMessageMetadata — The ``phoenix`` metadata namespace of an assistant message.
          - `type` 'assistant', required
          - `sessionId` string, required
          - `turnTraceContext` TurnTraceContext — The trace identity a turn's spans are parented to.
            - `traceId` string, required
            - `rootSpanId` string, required
            - `startedAt` string, date-time, required
          - `usage` AssistantMessageMetadataUsage
            - `tokens` AssistantMessageMetadataUsageTokens, required
              - …
            - `promptDetails` AssistantMessageMetadataUsageCacheTokenDetails — Prompt-cache token counts, mounted as the usage payload's ``prompt_details`` because cached tokens are a breakdown of the prompt.
              - …
          - `interrupted` boolean
        - PhoenixUserMessageMetadata — The ``phoenix`` metadata namespace the browser attaches to outgoing user messages.
          - `type` 'user', required
          - `currentDateTime` string, required
          - `timeZone` string, required
          - `isCompactionMessage` boolean
      - `pydantic_ai` PydanticAIMessageMetadata — Local pin of pydantic-ai's message-level ``pydantic_ai`` metadata namespace (its private ``_PydanticAIMessageMetadata``), merged into the assistant metadata by the stream's metadata chunk.
        - `timestamp` string, date-time, nullable
    - `parts` union[], required
      - union
        - TextUIPart — A text part of a message.
          - `type` 'text'
          - `text` string, required
          - `state` 'streaming' | 'done', nullable
          - `providerMetadata` object, nullable
        - ReasoningUIPart — A reasoning part of a message.
          - `type` 'reasoning'
          - `text` string, required
          - `state` 'streaming' | 'done', nullable
          - `providerMetadata` object, nullable
        - ToolInputStreamingPart — Tool part in input-streaming state.
          - `type` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'input-streaming'
          - `input` unknown
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - ToolInputAvailablePart — Tool part in input-available state.
          - `type` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'input-available'
          - `input` unknown
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputAvailablePart — Tool part in output-available state.
          - `type` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'output-available'
          - `input` unknown
          - `output` unknown
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `resultProviderMetadata` object, nullable
          - `preliminary` boolean, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputErrorPart — Tool part in output-error state.
          - `type` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'output-error'
          - `input` unknown
          - `rawInput` unknown
          - `errorText` string, required
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `resultProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - ToolApprovalRequestedPart — Tool part in approval-requested state (awaiting user decision).
          - `type` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'approval-requested'
          - `input` unknown
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - ToolApprovalRespondedPart — Tool part in approval-responded state (user approved/denied, execution pending).
          - `type` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'approval-responded'
          - `input` unknown
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - ToolOutputDeniedPart — Tool part in output-denied state (tool was denied, terminal state).
          - `type` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'output-denied'
          - `input` unknown
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - DynamicToolInputStreamingPart — Dynamic tool part in input-streaming state.
          - `type` 'dynamic-tool'
          - `toolName` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'input-streaming'
          - `input` unknown
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - DynamicToolInputAvailablePart — Dynamic tool part in input-available state.
          - `type` 'dynamic-tool'
          - `toolName` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'input-available'
          - `input` unknown, required
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputAvailablePart — Dynamic tool part in output-available state.
          - `type` 'dynamic-tool'
          - `toolName` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'output-available'
          - `input` unknown, required
          - `output` unknown, required
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `resultProviderMetadata` object, nullable
          - `preliminary` boolean, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputErrorPart — Dynamic tool part in output-error state.
          - `type` 'dynamic-tool'
          - `toolName` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'output-error'
          - `input` unknown, required
          - `errorText` string, required
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `resultProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - DynamicToolApprovalRequestedPart — Dynamic tool part in approval-requested state (awaiting user decision).
          - `type` 'dynamic-tool'
          - `toolName` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'approval-requested'
          - `input` unknown, required
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - DynamicToolApprovalRespondedPart — Dynamic tool part in approval-responded state (user approved/denied, execution pending).
          - `type` 'dynamic-tool'
          - `toolName` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'approval-responded'
          - `input` unknown, required
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - DynamicToolOutputDeniedPart — Dynamic tool part in output-denied state (tool was denied, terminal state).
          - `type` 'dynamic-tool'
          - `toolName` string, required
          - `toolCallId` string, required
          - `title` string, nullable
          - `state` 'output-denied'
          - `input` unknown, required
          - `providerExecuted` boolean, nullable
          - `callProviderMetadata` object, nullable
          - `approval` union
            - ToolApprovalRequested — Tool approval in requested state (awaiting user response).
              - …
            - ToolApprovalResponded — Tool approval in responded state (user has approved or denied).
              - …
        - SourceUrlUIPart — A source part of a message.
          - `type` 'source-url'
          - `sourceId` string, required
          - `url` string, required
          - `title` string, nullable
          - `providerMetadata` object, nullable
        - SourceDocumentUIPart — A document source part of a message.
          - `type` 'source-document'
          - `sourceId` string, required
          - `mediaType` string, required
          - `title` string, required
          - `filename` string, nullable
          - `providerMetadata` object, nullable
        - FileUIPart — A file part of a message.
          - `type` 'file'
          - `mediaType` string, required
          - `filename` string, nullable
          - `url` string, required
          - `providerMetadata` object, nullable
        - DataUIPart — Data part with dynamic type based on data name.
          - `type` string, required
          - `id` string, nullable
          - `data` unknown, required
        - StepStartUIPart — A step boundary part of a message.
          - `type` 'step-start'
  - `next_cursor` string, nullable, required

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Unprocessable Entity

---

[API](https://skmtc.net/arize-ai/apis/arize-phoenix-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-phoenix-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-phoenix-rest-api/revisions/8ac3f55fbe00/schema)