---
title: "List agent messages"
method: POST
path: "/agents/session/messages/list"
tags: ["Agents"]
---

# List agent messages

`POST /agents/session/messages/list`

Lists messages in a thread with pagination. Returns messages in a simplified format with user, assistant, and tool messages.

## Request body

- object — Request parameters for listing messages in a thread
  - `id` string, required — External ID of the thread to list messages for
  - `limit` integer — Maximum number of messages to return (default 1000, max 1000)
  - `offset` integer — Number of messages to skip for pagination

## Response `200`

Messages retrieved successfully

- object — Paginated list of messages in a thread
  - `messages` union[], required — List of messages in the thread
    - union — A message in the conversation
      - object — A message from the user
        - `role` 'user', required
        - `parts` union[], required — Content parts of the user message
          - union — A content part (text, file, or json)
            - object — A text content part
              - …
            - object — A file content part
              - …
            - object — A JSON content part
              - …
      - object — An assistant message with text content
        - `role` 'assistant', required
        - `parts` object[], required — Text content parts of the assistant reply
          - `type` 'text', required
          - `text` string, required — Text content
      - object — An assistant message with tool calls
        - `role` 'assistant', required
        - `parts` unknown[], required — Must be empty when calling tools
          - unknown
        - `toolCalls` object[], required — Tool calls made by the assistant
          - `id` string, required — Unique ID of the tool call
          - `type` 'function', required
          - `function` object, required
            - `name` string, required — Name of the function
            - `arguments` object, required — Arguments passed to the function
      - object — A tool result message
        - `role` 'tool', required
        - `toolCallId` string, required — ID of the tool call this message responds to
        - `parts` Union60[], required — Content parts of the tool result
          - union — A content part (text, file, or json)
            - object — A text content part
              - …
            - object — A file content part
              - …
            - object — A JSON content part
              - …
      - object — A developer/system message
        - `role` 'developer', required
        - `parts` Union60[], required — Content parts of the developer message
          - union — A content part (text, file, or json)
            - object — A text content part
              - …
            - object — A file content part
              - …
            - object — A JSON content part
              - …
  - `total` integer, required — Total number of messages in the thread

## Other responses

- `400` — Invalid request parameters
- `500` — Internal server error

---

[API](https://skmtc.dev/kaizenautomation/apis/kaizen-api.md) · [All operations](https://skmtc.dev/kaizenautomation/apis/kaizen-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kaizenautomation/kaizen-api/revisions/4aa3664ceff2/schema)