Skip to main content
Use the List Conversations API to retrieve conversation transcripts with metadata, timestamps, and states programmatically. Each conversation response includes a state field containing all conversation variables (conv.state values) set during the call – both built-in keys and custom variables your agent writes.
New integrations should use the Data API – List conversations endpoint (https://api.{region}.poly.ai/v1/agents/{agent_id}/conversations). It is the official supported offering. The legacy Conversations API v3 (https://api.{region}.platform.polyai.app/v3/{account_id}/{project_id}/conversations) remains available for existing integrations.

​
Push and pull

PolyAI supports both push and pull API models, offering flexible synchronization options:
  • Pull API: On-demand metadata retrieval through the List Conversations endpoint. Ideal for periodic data collection or workflows where updates are less time-sensitive.
  • Push API: Automatically sends updates (new conversations or completed interactions) to your system in real time. Best suited for dashboards requiring prompt updates.
For triggering instant communication updates for real-time use cases, like determining where to route a call, it is recommended to use handoff states.

​
Best practices

  1. Pull: Use this model for scheduled reporting or when real-time updates are unnecessary.
  2. Push: Use push updates for real-time synchronization, such as live agent dashboards.
  3. If you need real-time updates, use push. If periodic batch retrieval is sufficient, use pull.

​
Integration with other workflows

The List Conversations API can fit into a larger data-sharing workflow:
  1. Manual access using the studio: View richly-detailed conversation transcripts and recordings directly in the PolyAI platform.
  2. End of call metadata retrieval: Automate metadata syncing after conversations using push or pull APIs.
  3. Handoff metadata integration: Provide your live customer agent with a quick identifier indicating what kind of call they have just received.
Last modified on June 11, 2026