> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaizenautomation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List agent messages

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



## OpenAPI

````yaml post /agents/session/messages/list
openapi: 3.1.0
info:
  title: Kaizen API
  version: 1.0.0
  description: API for the Kaizen Automation Platform
servers:
  - url: https://api.kaizenautomation.com
    description: Production server
security: []
paths:
  /agents/session/messages/list:
    post:
      tags:
        - Agents
      summary: List agent messages
      description: >-
        Lists messages in a thread with pagination. Returns messages in a
        simplified format with user, assistant, and tool messages.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: External ID of the thread to list messages for
                  example: agent_conversation_thread_abc123
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 1000
                  description: >-
                    Maximum number of messages to return (default 1000, max
                    1000)
                offset:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Number of messages to skip for pagination
              required:
                - id
              description: Request parameters for listing messages in a thread
      responses:
        '200':
          description: Messages retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            role:
                              type: string
                              const: user
                            parts:
                              type: array
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      type:
                                        type: string
                                        const: text
                                      text:
                                        type: string
                                        description: Text content
                                    required:
                                      - type
                                      - text
                                    description: A text content part
                                  - type: object
                                    properties:
                                      type:
                                        type: string
                                        const: file
                                      fileId:
                                        type: string
                                        description: External ID of the file
                                        example: files_abc123
                                    required:
                                      - type
                                      - fileId
                                    description: A file content part
                                  - type: object
                                    properties:
                                      type:
                                        type: string
                                        const: json
                                      data:
                                        type: object
                                        additionalProperties: {}
                                        description: Structured JSON data
                                    required:
                                      - type
                                      - data
                                    description: A JSON content part
                                description: A content part (text, file, or json)
                              description: Content parts of the user message
                          required:
                            - role
                            - parts
                          description: A message from the user
                        - type: object
                          properties:
                            role:
                              type: string
                              const: assistant
                            parts:
                              type: array
                              items:
                                type: object
                                properties:
                                  type:
                                    type: string
                                    const: text
                                  text:
                                    type: string
                                    description: Text content
                                required:
                                  - type
                                  - text
                                description: A text content part
                              description: Text content parts of the assistant reply
                          required:
                            - role
                            - parts
                          description: An assistant message with text content
                        - type: object
                          properties:
                            role:
                              type: string
                              const: assistant
                            parts:
                              type: array
                              items: {}
                              maxItems: 0
                              description: Must be empty when calling tools
                            toolCalls:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                    description: Unique ID of the tool call
                                  type:
                                    type: string
                                    const: function
                                  function:
                                    type: object
                                    properties:
                                      name:
                                        type: string
                                        description: Name of the function
                                      arguments:
                                        type: object
                                        additionalProperties: {}
                                        description: Arguments passed to the function
                                    required:
                                      - name
                                      - arguments
                                required:
                                  - id
                                  - type
                                  - function
                                description: A tool call made by the assistant
                              description: Tool calls made by the assistant
                          required:
                            - role
                            - parts
                            - toolCalls
                          description: An assistant message with tool calls
                        - type: object
                          properties:
                            role:
                              type: string
                              const: tool
                            toolCallId:
                              type: string
                              description: ID of the tool call this message responds to
                            parts:
                              type: array
                              items:
                                $ref: '#/components/schemas/Union_58'
                              description: Content parts of the tool result
                          required:
                            - role
                            - toolCallId
                            - parts
                          description: A tool result message
                        - type: object
                          properties:
                            role:
                              type: string
                              const: developer
                            parts:
                              type: array
                              items:
                                $ref: '#/components/schemas/Union_58'
                              description: Content parts of the developer message
                          required:
                            - role
                            - parts
                          description: A developer/system message
                      description: A message in the conversation
                    description: List of messages in the thread
                  total:
                    type: integer
                    description: Total number of messages in the thread
                required:
                  - messages
                  - total
                description: Paginated list of messages in a thread
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
components:
  schemas:
    Union_58:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              const: text
            text:
              type: string
              description: Text content
          required:
            - type
            - text
          description: A text content part
        - type: object
          properties:
            type:
              type: string
              const: file
            fileId:
              type: string
              description: External ID of the file
              example: files_abc123
          required:
            - type
            - fileId
          description: A file content part
        - type: object
          properties:
            type:
              type: string
              const: json
            data:
              type: object
              additionalProperties: {}
              description: Structured JSON data
          required:
            - type
            - data
          description: A JSON content part
      description: A content part (text, file, or json)

````