Conversations

The Conversations API lets you list agent conversations, retrieve individual conversation details, read message history, and inspect token usage. Conversations are created automatically when agents process tasks, whether triggered by skill execution, scheduled jobs, or webhook events.

---

List Conversations

GET/api/conversations

Retrieve a paginated list of conversations, optionally filtered by agent, user, status, or trigger type.

Requires authentication via x-api-key header.

Query Parameters

Parameter	Type	Description
agent_id	string	Filter conversations by a specific agent.
user_id	string	Filter conversations by the user who initiated them.
status	string	Filter by conversation status (e.g., 'active', 'completed', 'failed').
trigger_type	string	Filter by how the conversation was initiated (e.g., 'api', 'webhook', 'scheduled').
limit	number	Maximum number of results to return. Default: 50, Max: 200.
offset	number	Number of results to skip for pagination. Default: 0.

Request

curl -X GET "https://api.horizonplatform.ai/api/conversations?agent_id=agent_001&status=completed&limit=10" \
  -H "x-api-key: hz_live_abc123def456"

const params = new URLSearchParams({
  agent_id: 'agent_001',
  status: 'completed',
  limit: '10',
});

const response = await fetch(
  `https://api.horizonplatform.ai/api/conversations?${params}`,
  { headers: { 'x-api-key': 'hz_live_abc123def456' } }
);

const conversations = await response.json();

import requests

response = requests.get(
    'https://api.horizonplatform.ai/api/conversations',
    headers={'x-api-key': 'hz_live_abc123def456'},
    params={
        'agent_id': 'agent_001',
        'status': 'completed',
        'limit': 10,
    }
)

conversations = response.json()

Response

// 200 OK
[
  {
    "id": "conv_8f3a2b1c",
    "agent_id": "agent_001",
    "user_id": "user_42",
    "status": "completed",
    "trigger_type": "api",
    "created_at": "2026-03-18T14:30:00Z",
    "updated_at": "2026-03-18T14:31:12Z"
  },
  {
    "id": "conv_7e2d1a0b",
    "agent_id": "agent_001",
    "user_id": "user_42",
    "status": "completed",
    "trigger_type": "scheduled",
    "created_at": "2026-03-18T09:00:00Z",
    "updated_at": "2026-03-18T09:02:45Z"
  }
]

---

Get a Conversation

GET/api/conversations/:id

Retrieve a single conversation by ID, including token usage statistics.

Requires authentication via x-api-key header.

Path Parameters

Parameter	Type	Description
id required	string	The unique conversation identifier.

Request

curl -X GET https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c \
  -H "x-api-key: hz_live_abc123def456"

const response = await fetch(
  'https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c',
  { headers: { 'x-api-key': 'hz_live_abc123def456' } }
);

const conversation = await response.json();

import requests

response = requests.get(
    'https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c',
    headers={'x-api-key': 'hz_live_abc123def456'}
)

conversation = response.json()

Response

// 200 OK
{
  "id": "conv_8f3a2b1c",
  "agent_id": "agent_001",
  "user_id": "user_42",
  "status": "completed",
  "trigger_type": "api",
  "token_stats": {
    "prompt_tokens": 1250,
    "completion_tokens": 830,
    "total_tokens": 2080
  },
  "created_at": "2026-03-18T14:30:00Z",
  "updated_at": "2026-03-18T14:31:12Z"
}

The token_stats object provides a summary of token consumption for the entire conversation, useful for cost tracking and usage monitoring.

---

List Conversation Messages

GET/api/conversations/:id/messages

Retrieve the message history for a conversation, optionally filtered by role.

Requires authentication via x-api-key header.

Path Parameters

Parameter	Type	Description
id required	string	The conversation identifier.

Query Parameters

Parameter	Type	Description
role	string	Filter messages by role (e.g., 'user', 'assistant', 'system').
limit	number	Maximum number of messages to return. Default: 100, Max: 500.
offset	number	Number of messages to skip for pagination. Default: 0.

Request

curl -X GET "https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c/messages?role=assistant&limit=20" \
  -H "x-api-key: hz_live_abc123def456"

const params = new URLSearchParams({
  role: 'assistant',
  limit: '20',
});

const response = await fetch(
  `https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c/messages?${params}`,
  { headers: { 'x-api-key': 'hz_live_abc123def456' } }
);

const messages = await response.json();

import requests

response = requests.get(
    'https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c/messages',
    headers={'x-api-key': 'hz_live_abc123def456'},
    params={
        'role': 'assistant',
        'limit': 20,
    }
)

messages = response.json()

Response

// 200 OK
[
  {
    "id": "msg_001",
    "conversation_id": "conv_8f3a2b1c",
    "role": "user",
    "content": "Generate a Profit & Loss report for Q1 2026.",
    "created_at": "2026-03-18T14:30:00Z"
  },
  {
    "id": "msg_002",
    "conversation_id": "conv_8f3a2b1c",
    "role": "assistant",
    "content": "I'll pull the P&L report from QuickBooks for January 1 through March 31, 2026...",
    "created_at": "2026-03-18T14:30:15Z"
  },
  {
    "id": "msg_003",
    "conversation_id": "conv_8f3a2b1c",
    "role": "assistant",
    "content": "Here is your Profit & Loss report for Q1 2026:\n\nTotal Income: $245,000\nTotal Expenses: $182,000\nNet Income: $63,000\n...",
    "created_at": "2026-03-18T14:31:12Z"
  }
]

---

Get Token Usage

GET/api/conversations/:id/token-usage

Get a detailed breakdown of token usage for a specific conversation.

Requires authentication via x-api-key header.

Path Parameters

Parameter	Type	Description
id required	string	The conversation identifier.

Request

curl -X GET https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c/token-usage \
  -H "x-api-key: hz_live_abc123def456"

const response = await fetch(
  'https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c/token-usage',
  { headers: { 'x-api-key': 'hz_live_abc123def456' } }
);

const tokenUsage = await response.json();

import requests

response = requests.get(
    'https://api.horizonplatform.ai/api/conversations/conv_8f3a2b1c/token-usage',
    headers={'x-api-key': 'hz_live_abc123def456'}
)

token_usage = response.json()

Response

// 200 OK
{
  "conversation_id": "conv_8f3a2b1c",
  "prompt_tokens": 1250,
  "completion_tokens": 830,
  "total_tokens": 2080,
  "breakdown": [
    {
      "message_id": "msg_001",
      "role": "user",
      "prompt_tokens": 45,
      "completion_tokens": 0
    },
    {
      "message_id": "msg_002",
      "role": "assistant",
      "prompt_tokens": 605,
      "completion_tokens": 320
    },
    {
      "message_id": "msg_003",
      "role": "assistant",
      "prompt_tokens": 600,
      "completion_tokens": 510
    }
  ]
}

Tip

Use token usage data to monitor costs, identify expensive conversations, and optimize agent instructions to reduce token consumption.

---

Error Responses

Status	Error	Description
401	authentication_required	Missing or invalid API key.
403	insufficient_scope	API key lacks the required scope.
404	not_found	The specified conversation does not exist.
400	validation_error	Invalid query parameter values (e.g., limit exceeds maximum).