The Data API provides programmatic access to conversation records, audio recordings, annotations, notes, and debug chat sessions generated by your PolyAI agents. Use it for analytics pipelines, QA workflows, compliance reporting, and interactive testing.
What you can do
- List conversations for a project and retrieve full conversation detail by ID.
- Fetch the WAV audio recording for a conversation (with PII-redaction controls).
- Add turn-level annotations (
missing_topic, wrong_transcript, wrong_info) to flag issues for review.
- Upsert free-form notes on a conversation.
- Create and exchange messages in debug chat sessions to test agent variants outside of production traffic.
Regional base URLs
| Region | Base URL |
|---|
| US | https://api.us.poly.ai |
| EU | https://api.eu.poly.ai |
| UK | https://api.uk.poly.ai |
| Studio | https://api.studio.poly.ai |
Identifiers
Agent Studio labels and API parameters use different names for the same things. When you read an ID from Agent Studio, map it to the API parameter using this table:
| Agent Studio label | API parameter | Example |
|---|
| Workspace ID | accountId | ws-fd112d8f |
| Project ID / Agent ID | agentId | PROJECT-58RP822I |
Agent ID is the same value as Project ID. “Agent” is the current product name; “Project” is the legacy term still surfaced in some Agent Studio screens and URLs. Use the value you see in Agent Studio as the agentId path parameter — no transformation needed.
Authentication
The Data API uses API key authentication with the X-API-KEY header. API keys are scoped to account, project, and region. Issue keys from the API keys section of Agent Studio, or request one from your PolyAI representative.
curl --request GET \
--url "https://api.us.poly.ai/v1/agents/{agentId}/conversations" \
--header "X-API-KEY: $POLYAI_API_KEY"
The Agent Studio instance and API region must match. A key generated from studio.poly.ai only works against api.studio.poly.ai. To call api.us.poly.ai, you must generate the key from studio.us.poly.ai (and likewise for eu and uk). A mismatch returns 401 Unauthorized.| Agent Studio URL | API base URL |
|---|
https://studio.poly.ai | https://api.studio.poly.ai |
https://studio.us.poly.ai | https://api.us.poly.ai |
https://studio.eu.poly.ai | https://api.eu.poly.ai |
https://studio.uk.poly.ai | https://api.uk.poly.ai |
