Sign in

v1

latestOpenAPI 3.1.02026-07-2687120159.0 KB
Conversations

List conversations for a project

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

Path parameters

account_idstring required

Account ID

project_idstring required

Project ID

Query parameters

query_type'transcript' | 'semantic'

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.

sample'random'

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

querystring

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

turn_type'user' | 'agent'

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

channelstring[]

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

client_env'sandbox' | 'pre-release' | 'live'

Client Environment - sandbox, pre-release or live

start_timestring date-time

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

end_timestring date-time

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

limitinteger

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

offsetinteger

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.

cursorstring

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_idstring

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_namestring

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_progressboolean

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_latencyboolean

If true, include the latency info for each conversation.

Response

OK

next_offsetinteger

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.

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

Example response

{
  "conversations": [
    {
      "id": "CAabcd1234567abcdef1250065d4fc7389"
    }
  ]
}