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 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 migrate to v3 before support ends. See the v1 to v3 migration guide for a step-by-step walkthrough.
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–5000) | 5 |
offset | Pagination offset | 0 |
Optional response fields
| Parameter | Description | Default |
|---|
include_latency | Include latency metrics per conversation | false |
include_turn_metadata | Include additional generative AI metadata for each turn. This does not control whether the turns array is returned — turns are always included. | 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 | Conversation medium. Common values: VOICE-SIP (voice/telephony), WEBCHAT (webchat widget), CHAT (agent chat). These are analytics-level labels — for runtime channel detection in custom functions, see conv.channel_type. |
from_number | Caller phone number |
to_number | Agent phone number |
in_progress | Whether call is still active |
num_turns | Total number of turns in the conversation (integer count) |
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 | All conversation variables (conv.state values) set during the call, returned as key-value pairs. Includes both built-in keys (e.g. from_, to, call_sid) and any custom variables your agent writes. |
turns | Ordered list of conversation turn objects. May be empty if transcript access is disabled in your project’s API configuration (see transcript visibility). |
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)
These three fields are often confused. Here’s how they relate:
| Field | Type | Purpose |
|---|
turns | Array of turn objects | The full ordered list of conversation turns. Included by default, but may be empty if transcript access is disabled in the project’s API configuration. |
num_turns | Integer | A count of turns in the conversation. This value reflects the number of turns that occurred, even if the turns array is empty due to configuration. |
include_turn_metadata | Query parameter (boolean) | When true, adds an extra metadata field to each turn with generative AI details. Does not control whether the turns array itself is populated. |
Setting include_turn_metadata=true enriches each turn object with additional generative AI metadata. It does not affect whether turns are returned — the turns array population is controlled by your project’s API configuration, not by this parameter.
Transcript visibility
The turns array in the API response is controlled by the transcript visibility setting in your project’s API configuration. When transcript access is disabled (show_transcripts: false), the API returns an empty turns array even though num_turns still reports the actual count.
If you need turn-level data and turns is empty, contact your PolyAI representative to check or update your project’s API configuration.
Troubleshooting
turns is empty but num_turns is greater than zero
If num_turns reports a count but the turns array is empty:
- Check your project’s API configuration. Transcript visibility may be disabled for your project. This is the most common cause — the
turns array is intentionally empty when show_transcripts is set to false. Contact your PolyAI representative to verify or update this setting.
- Check if the conversation is still in progress. If
in_progress is true, turn data may still be arriving and may not be fully available yet.
- Contact your PolyAI representative if neither of the above applies. This may indicate a data pipeline delay or ingestion issue.
