List all 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.

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

cURL

cURL

curl --request GET \
  --url https://api.us-1.platform.polyai.app/v3/{account_id}/{project_id}/conversations \
  --header 'x-api-key: <api-key>'

200

{
  "conversations": [
    {
      "id": "CAabcd1234567abcdef1250065d4fc7389",
      "account_id": "<string>",
      "project_id": "<string>",
      "environment": "<string>",
      "started_at": "2023-11-07T05:31:56Z",
      "channel": "<string>",
      "in_progress": true,
      "variant_id": "<string>",
      "variant_name": "<string>",
      "from_number": "<string>",
      "to_number": "<string>",
      "num_turns": 123,
      "total_duration": 123,
      "polyai_duration": 123,
      "handoff": true,
      "handoff_reason": "<string>",
      "handoff_destination": "<string>",
      "num_silences": 123,
      "num_ood": 123,
      "metrics": {
        "CALL_DURATION": "30",
        "CALL_TURN": [
          "2022-02-18T12:09:05.12677Z",
          "2022-02-18T12:09:17.90602Z",
          "2022-02-18T12:09:29.57732Z",
          "2022-02-18T12:09:35.36996Z"
        ]
      },
      "state": {},
      "turns": [
        {
          "user_input": "<string>",
          "user_input_dtmf": "<string>",
          "user_input_datetime": "2023-11-07T05:31:56Z",
          "agent_response": "<string>",
          "agent_response_datetime": "2023-11-07T05:31:56Z",
          "latency": 123,
          "translated_user_input": "<string>",
          "english_agent_response": "<string>",
          "intents": [
            "<string>"
          ],
          "entities": [
            {}
          ],
          "is_ood": true,
          "is_silence": true
        }
      ]
    }
  ],
  "next_offset": 123,
  "cursor": "<string>"
}

Authorizations

x-api-key · string · header · required

Contact your PolyAI representative.

Path Parameters

account_id · string · required

Account ID

project_id · string · required

Project ID

Query Parameters

query_type · enum<string>

Search mode. Use transcript for full-text search over conversation transcripts, or semantic for vector similarity search. Requires query to be set. Mutually exclusive with sample.

Available options: transcript, semantic

sample · enum<string>

Sampling mode. Use random to return a random sample of conversations within the time range. No query required. Mutually exclusive with query_type.

Available options: random

query · string

The search text used for transcript or semantic search. Required when query_type is set.

turn_type · enum<string>

Transcript search only. Filter by user or agent turns. Defaults to both.

Available options: user, agent

channel · string[]

One or more channels to filter by (e.g. voice, chat). Can be specified multiple times.

client_env · enum<string> · default: live

Client Environment - sandbox, pre-release or live

Available options: sandbox, pre-release, live

start_time · string<date-time>

The start of the time range of the conversations to get, in ISO8601 format

end_time · string<date-time>

The end of the time range of the conversations to get, in ISO8601 format

limit · integer · default: 1000

Max number of conversations to return per API call. If the result set of your query is larger than this, it will be paginated.

Required range: 1 <= x <= 1000

offset · integer · default: 0

Offset within result set to fetch. Prefer cursor for paginating through large result sets — offset-based pagination becomes progressively slower at scale and may drift when conversations are written concurrently.

Required range: x >= 0

cursor · string

Opaque cursor for keyset pagination. Omit on the first request, then pass the cursor value returned by the previous response to fetch the next page. Cursors are URL-safe, encode the position within the result set, and remain stable as new conversations are written. Mutually preferable to offset for paginating through large result sets. Returns a 400 if the cursor value is malformed.

variant_id · string

If it is set, we would return all conversations under this variant_id. Note that you may only specify either one of the variant_id or variant_name.

variant_name · string

If it is set, we would return all conversations under this variant_name. Note that you may only specify either one of the variant_id or variant_name. Also, make sure to encode any spaces in the name with "%20"

in_progress · boolean

If it is set to false, we only return finished conversations. If it is set to true, we only return conversations still in progress. By default, this parameter is None and we return all conversations.

include_latency · boolean · default: false

If true, include the latency info for each conversation.

include_turn_metadata · boolean · default: false

If true, include additional generative AI metadata for each conversation turn. This does not control whether the turns array is returned — turns are always included in the response.

Response

200

application/json

OK

conversations · object[]

Show child attributes

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 | null

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.