The Conversations API provides programmatic access to the conversation records generated by PolyAI agents. It returns transcripts, turn-by-turn metadata, handoff information, and performance metrics in a structured format suitable for analytics pipelines and integrations.
Most customers should use v3, the latest most performant version.
API versions
Only the Conversations API is versioned. Other APIs are currently unversioned.
v3 – current and recommended
v3 is the fully supported release of the Conversations API.
It runs on PolyAI’s event-sourced data platform and improves on v1 by offering:
- reliable, scalable ingestion and querying
- consistent ISO8601 timestamps
- empty strings ("") instead of
null for empty text fields
- additional turn-level metadata such as
latency, translated_user_input, and english_agent_response
Authentication for v3 is managed internally by PolyAI.
Customers must request v3 access through their PolyAI representative.
Example base path:
https://api.{region}.platform.polyai.app/v3/{account_id}/{project_id}/conversations
v2 uses the same schema and event-sourced backend as v3, but retains the legacy authentication model. Existing customers can continue using v2, but new customers should use v3
v1 – legacy
v1 uses an earlier data pipeline and the legacy authentication system.
Deprecation timeline
- From 2 March 2026, v1 moves to best-effort support (no SLA).
- From 31 August 2026, v1 remains available but is no longer supported.
Customers on v1 should plan migration to v3 before support ends.
Regional base URLs
| Region | Base URL |
|---|
| US | https://api.us-1.platform.polyai.app |
| UK | https://api.uk-1.platform.polyai.app |
| EUW | https://api.euw-1.platform.polyai.app |
https://api.{region}.platform.polyai.app/{version}/{account_id}/{project_id}/conversations
Authentication
The Conversations API uses API key authentication.
v3 keys
v3 keys are project- and region-scoped and are issued by PolyAI.
Your PolyAI representative will confirm the appropriate scope and provision access.
Query parameters
The Conversations API supports several query parameters for filtering and controlling the response:
Required parameters
| Parameter | Description |
|---|
start_time | Start of time range (ISO8601) |
end_time | End of time range (ISO8601) |
Optional filters
| Parameter | Description | Default |
|---|
client_env | Environment: sandbox, pre-release, or live | live |
variant_id | Filter by variant ID | — |
variant_name | Filter by variant name (URL-encode spaces with %20) | — |
in_progress | Filter by conversation status: true for in-progress, false for finished | all |
limit | Max conversations per request (1–1000) | 5 |
offset | Pagination offset | 0 |
Optional response fields
| Parameter | Description | Default |
|---|
include_latency | Include latency metrics per conversation | false |
include_context_state | Include agent’s internal dialogue state at conversation end | false |
include_turn_metadata | Include genai metadata for each turn | false |
Response structure
Conversation object
| Field | Description |
|---|
id | Unique conversation ID |
account_id | Customer account ID |
project_id | Project ID |
variant_id | Variant ID |
variant_name | Variant name |
environment | Deployment environment (live, sandbox, pre-release) |
started_at | Conversation start time (ISO8601) |
channel | Medium: CHAT, VOICE-SIP, etc. |
from_number | Caller phone number |
to_number | Agent phone number |
in_progress | Whether call is still active |
num_turns | Number of turns |
total_duration | Total call duration (seconds) |
polyai_duration | PolyAI-handled duration (seconds) |
handoff | Whether handoff occurred |
handoff_reason | Brief handoff reason |
handoff_destination | Handoff destination |
num_silences | Count of silence turns |
num_ood | Count of out-of-domain turns |
metrics | Custom metrics logged by agent |
state | Dialogue state key-value pairs |
turns | Ordered list of conversation turns |
Turn object
| Field | Description |
|---|
user_input | User’s transcribed text |
user_input_datetime | When agent received input (ISO8601) |
barge_in | Whether user interrupted the agent |
agent_response | Agent’s response text |
agent_response_datetime | When agent responded (ISO8601) |
intents | Detected intents |
entities | Detected entities (name → value mapping) |
is_ood | Whether turn was out-of-domain |
is_silence | Whether turn was a silence |
translated_user_input | Translated user input (when enabled) |
english_agent_response | English version of response (when enabled) |
next_offset. Use this value as the offset parameter in your next request to fetch the next page.
Example: Retrieve conversations (v3)
GET https://api.{region}.platform.polyai.app/v3/{account_id}/{project_id}/conversations
A successful response includes:
- complete turn-by-turn transcript
- consistent timestamps
- latency metrics (when
include_latency=true)
- translation outputs (when enabled)
- handoff metadata (if applicable)
