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
}

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: 5

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 <= 5000

offset · integer · default: 0

Offset within result set to fetch.

Required range: x >= 0

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