Skip to main content
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: 
Authorization: Bearer YOUR_API_KEY

​
Listing Messages

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

​
Request

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

​
Response

{
  "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

ParameterTypeDefaultDescription
threadIdstring-Required. External ID of the thread.
limitnumber1000Maximum messages to return (1-1000).
offsetnumber0Number of messages to skip from the beginning.

​
Example: Fetching the Second Page

curl --request POST \
    --url https://api.kaizenautomation.com/agents/session/messages/list \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "threadId": "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. 
{
  "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: 
{
  "role": "assistant",
  "parts": [
    { "type": "text", "text": "Here are the product details I found..." }
  ]
}
Tool call — the agent invokes one or more tools: 
{
  "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. 
{
  "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. 
{
  "role": "developer",
  "parts": [{ "type": "text", "text": "Downloads completed: report.pdf" }]
}

​
Content Part Types

Each message contains an array of parts. The supported types are:
TypeFieldsDescription
texttextPlain text content.
filefileIdReference to an uploaded file.
jsondataStructured 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.