---
title: "List conversations for a project"
method: GET
path: "/v3/{account_id}/{project_id}/conversations"
tags: ["Conversations"]
---

# List conversations for a project

`GET /v3/{account_id}/{project_id}/conversations`

Retrieves conversations for a given account and project. Supports three retrieval modes: transcript search, semantic search, and random sampling. When no retrieval mode is specified, the endpoint returns all conversations matching the given filters (default behavior). Only one retrieval mode may be specified per request.

## Path parameters

- `account_id` string, required
- `project_id` string, required

## Query parameters

- `query_type` 'transcript' | 'semantic'
- `sample` 'random'
- `query` string
- `turn_type` 'user' | 'agent'
- `channel` string[]
- `client_env` 'sandbox' | 'pre-release' | 'live'
- `start_time` string, date-time
- `end_time` string, date-time
- `limit` integer
- `offset` integer
- `cursor` string
- `variant_id` string
- `variant_name` string
- `in_progress` boolean
- `include_latency` boolean

## Response `200`

OK

- GetConversationsResponse — A page of conversations matching the query, plus pagination data.
  - `conversations` ConversationSummaryResponse[], required
    - `id` string, required — Unique ID for this conversation
    - `account_id` string, required — ID of the customer account this conversation is under.
    - `project_id` string, required — ID of the project this conversation is under.
    - `variant_id` string — ID of the variant this conversation is in.
    - `variant_name` string — Name of the variant this conversation is in.
    - `environment` string, required — Which deployment environment this conversation was handled in. Usually `live`, `sandbox`, or `pre-release`.
    - `started_at` string, date-time, required — The time when the conversation began, in ISO8601 format.
    - `channel` string, required — What medium the conversation took place in. Usually one of `WEBCHAT` or `VOICE-SIP`.
    - `from_number` string — Caller's phone number.
    - `to_number` string — Phone number of the agent the caller was connected to.
    - `in_progress` boolean, required — If true, the call is currently in progress, and therefore its properties may still change in the future.
    - `num_turns` integer — Total number of turns in the conversation. This count should match the length of the turns array.
    - `total_duration` integer — Duration of the entire call, in seconds.
    - `polyai_duration` integer — Duration of the portion of the call handled by the PolyAI agent, in seconds.
    - `handoff` boolean — Whether or not the PolyAI agent handed the call off.
    - `handoff_reason` string — Brief reason why the agent handed the call off.
    - `handoff_destination` string — If there are multiple handoff destinations, which one was used.
    - `num_silences` integer — Number of turns in the conversation where the caller gave no discernible input.
    - `num_ood` integer — Number of turns in the conversation where the caller gave some input, but it could not be understood by our agent.
    - `metrics` object — Mapping name -> value of custom metrics logged by the agent. If a metric name was written more than once, the value will be a list of the values that were written. Timestamps, where present, use a consistent ISO8601 date-time format.
    - `state` object — Mapping of keys -> values written to the dialogue state by the agent.
    - `turns` ConversationTurn[] — Ordered list of turn objects in the conversation. May be empty if transcript access is disabled in the project's API configuration, even when num_turns is non-zero.
      - `user_input` string — The transcription of what the user spoke or typed. May be an empty string when no input is present.
      - `user_input_dtmf` string — DTMF digits captured for this turn (e.g. keypad input). May be an empty string when no DTMF was entered.
      - `user_input_datetime` string, date-time — The time when the agent received the user's input. For speech, this is when ASR finished transcribing.
      - `agent_response` string — The transcription of the agent's response to the user. May be an empty string when no response was produced.
      - `agent_response_datetime` string, date-time — The time when the agent responded. For speech, this is when the agent started speaking.
      - `latency` number — Agent latency for this turn (for example, time in seconds between receiving user input and starting the agent response).
      - `translated_user_input` string — User input translated into the agent's working language (typically English) if translation is enabled. May be an empty string when not applicable.
      - `english_agent_response` string — Agent response in English when translation is enabled. May be an empty string when not applicable.
      - `intents` string[] — The list of intents that were found in this turn's input.
      - `entities` object[] — The list of entities that were found in this turn's input.
      - `is_ood` boolean — Whether the turn is classified as Out of Domain (OOD).
      - `is_silence` boolean — Whether the turn is classified as a silence.
  - `next_offset` integer — If present, the result is being paginated and requires another API call to fetch the next portion (pass the provided `next_offset` as the `offset` param for the next API call). For new integrations, prefer the `cursor` field for faster, drift-free pagination.
  - `cursor` string, nullable — Opaque cursor pointing to the start of the next page. Pass this value as the `cursor` query parameter on the next request to fetch the following page. `null` when there are no more pages.

## Other responses

- `400` — Validation error.
- `401` — Missing or invalid API key.
- `403` — Missing or invalid API key.
- `404` — Resource not found.
- `500` — Internal Server Error.

---

[API](https://skmtc.net/poly/apis/polyai-agents-api.md) · [All operations](https://skmtc.net/poly/apis/polyai-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/poly/polyai-agents-api/revisions/76f3c606e395/schema)