> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# List conversations

> Retrieve conversation transcripts and metadata programmatically using the Conversations API.

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](/agent-studio/tools/variables) (`conv.state` values) set during the call – both built-in keys and custom variables your agent writes.

> **Tip**
>
> **New integrations should use the [Data API – List conversations](/api-reference/api-reference/data/list-conversations) endpoint** (`https://api.{region}.poly.ai/v1/agents/{agent_id}/conversations`). It is the official supported offering. The legacy [Conversations API v3](/api-reference/legacy/conversations-api-v-3-legacy/overview) (`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:

```mermaid
flowchart LR
    subgraph Pull["Pull model"]
        direction LR
        A[Your system] -->|Periodic request| B[PolyAI API]
        B -->|Conversation data| A
    end
    subgraph Push["Push model"]
        direction LR
        C[PolyAI] -->|Real-time webhook| D[Your system]
    end
```

* **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.

> **Note**
>
> For triggering **instant** communication updates for real-time use cases, like determining where to route a call, it
> is recommended to use [handoff states](/agent-studio/account/call-data/api-and-export/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](/agent-studio/account/call-data/studio-transcripts): 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**](/agent-studio/account/call-data/api-and-export/handoff-states): Provide your live customer agent with a quick identifier indicating what kind of call they have just received.