> ## 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.

# Listing Agent Messages via API

> Learn how to retrieve paginated agent conversation messages using the Kaizen API, including user messages, assistant replies, and tool call results.

This guide walks you through using the Kaizen API to list messages from an agent conversation thread. The endpoint returns messages in a simplified format with pagination support.

## Overview

The `/agents/session/messages/list` endpoint lets you retrieve messages from a conversation thread. This is useful when you want to:

* Display conversation history in an external UI
* Process or analyze past agent interactions
* Build integrations that react to agent conversation content

## Prerequisites

Before you begin, make sure you have:

1. A Kaizen API key (found in your organization settings)
2. A thread ID from an existing agent conversation

## Authentication

All API requests require a Bearer token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Listing Messages

Send a POST request with the thread `id` to retrieve messages. The endpoint returns up to 1000 messages per page.

### Request

```bash theme={null}
curl --request POST \
    --url https://api.kaizenautomation.com/agents/session/messages/list \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "agent_conversation_thread_abc123"
  }'
```

### Response

```json theme={null}
{
  "messages": [
    {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Go to example.com and extract the main heading"
        }
      ]
    },
    {
      "role": "assistant",
      "parts": [],
      "toolCalls": [
        {
          "id": "agent_conversation_thread_messages_content_part_abc123",
          "type": "function",
          "function": {
            "name": "NavigateToUrl",
            "arguments": {
              "url": "https://example.com"
            }
          }
        }
      ]
    },
    {
      "role": "tool",
      "toolCallId": "agent_conversation_thread_messages_content_part_abc123",
      "parts": [
        {
          "type": "text",
          "text": "Successfully navigated to https://example.com"
        }
      ]
    },
    {
      "role": "assistant",
      "parts": [
        {
          "type": "text",
          "text": "The main heading on example.com is \"Example Domain\"."
        }
      ]
    }
  ],
  "total": 4
}
```

## Pagination

The endpoint supports offset-based pagination. Use the `limit` and `offset` parameters to page through results.

### Parameters

| Parameter | Type   | Default | Description                                    |
| --------- | ------ | ------- | ---------------------------------------------- |
| `id`      | string | -       | **Required.** External ID of the thread.       |
| `limit`   | number | 1000    | Maximum messages to return (1-1000).           |
| `offset`  | number | 0       | Number of messages to skip from the beginning. |

### Example: Fetching the Second Page

```bash theme={null}
curl --request POST \
    --url https://api.kaizenautomation.com/agents/session/messages/list \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "agent_conversation_thread_abc123",
    "limit": 1000,
    "offset": 1000
  }'
```

Use the `total` field in the response to determine how many pages exist.

## Message Types

Every message has a `role` field indicating who sent it.

### User Messages

Sent by the user to instruct the agent. Contains an array of content parts.

```json theme={null}
{
  "role": "user",
  "parts": [
    { "type": "text", "text": "Extract the product details" },
    { "type": "file", "fileId": "files_abc123" }
  ]
}
```

### Assistant Messages

Sent by the agent. There are two variants:

**Text reply** -- the agent responds with text content:

```json theme={null}
{
  "role": "assistant",
  "parts": [
    { "type": "text", "text": "Here are the product details I found..." }
  ]
}
```

**Tool call** -- the agent invokes one or more tools:

```json theme={null}
{
  "role": "assistant",
  "parts": [],
  "toolCalls": [
    {
      "id": "content_part_id",
      "type": "function",
      "function": {
        "name": "ClickElement",
        "arguments": { "elementDescription": "Submit button" }
      }
    }
  ]
}
```

### Tool Messages

Results returned by a tool invocation. The `toolCallId` links back to the corresponding tool call.

```json theme={null}
{
  "role": "tool",
  "toolCallId": "content_part_id",
  "parts": [{ "type": "text", "text": "Button clicked successfully" }]
}
```

### Developer Messages

System-level messages generated during the conversation (e.g., file downloads completed, CAPTCHA solving events, tab creation). These provide context about background operations.

```json theme={null}
{
  "role": "developer",
  "parts": [{ "type": "text", "text": "Downloads completed: report.pdf" }]
}
```

## Content Part Types

Each message contains an array of `parts`. The supported types are:

| Type   | Fields   | Description                     |
| ------ | -------- | ------------------------------- |
| `text` | `text`   | Plain text content.             |
| `file` | `fileId` | Reference to an uploaded file.  |
| `json` | `data`   | Structured key-value JSON data. |

## Summary

The List Messages API gives you paginated access to full agent conversation history. Use it to build custom UIs, analyze agent behavior, or integrate agent results into downstream systems.