List conversations

View as Markdown
Return matching records as data[], with pagination.has_more and pagination.next_cursor. Each item uses the same native payload as single-record retrieval. Required start_time/end_time are epoch seconds with an inclusive start and exclusive end, spanning at most 31 days. limit is 1–50 (default 20); sort_order is asc or desc (default desc). Optional filter applies the same standard field matching as the dashboard. The record follows the existing analytics webhook format: audio_to_text.transcript for calls or chat_transcription.transcript for chats, meta_analytics and native conversation_analytics modules. Customer analytics and customer timeline are excluded. For larger datasets, use [Create export](/v0/api-reference/exports/create-export) to obtain a CSV download link. Each export supports at most 31 days, 100,000 records and 100 MB; split longer periods into adjacent windows.

Authentication

AuthorizationBearer
Existing private account API key from Developer Hub. Keep it on your backend.

Query parameters

service_idstringRequired1-255 characters

Required authorized service. Client identity is derived from the API key. Nonempty, at most 255 characters; whitespace-only values and control characters are rejected.

time_fieldenumOptionalDefaults to conversation_time

Timestamp used for filtering and ordering. Only conversation_time is currently supported for this resource.

Allowed values:
start_timelongRequired0-253402300799

Inclusive start in Unix epoch seconds. Must precede end_time; maximum window is 31 days. Milliseconds are invalid.

end_timelongRequired0-253402300799
Exclusive end in Unix epoch seconds. Maximum window is 31 days. Milliseconds are invalid.
channelenumOptional
Optional source channel.
Allowed values:
customer_idstringOptional1-255 characters

Optional explicit linked customer ID. Nonempty, at most 255 characters; whitespace-only values and control characters are rejected.

analysis_statusenumOptional

Filter persisted analysis by completed or failed. Ingestion-queue states are not exposed.

Allowed values:
sort_orderenumOptionalDefaults to desc

Order by conversation_time, then ID in the same direction. asc returns oldest first; desc returns newest first. Keep the same sort_order when continuing with a cursor.

Allowed values:
limitintegerOptional1-50Defaults to 20

Maximum records per page. Accepts integers from 1 to 50; defaults to 20.

cursorstringOptional1-4096 characters

Opaque continuation token, 1–4,096 characters; expires after 15 minutes. Repeat the same filters and sort_order. Omit for the first page. Copy pagination.next_cursor from the previous response; see the pagination walkthrough for first and next-page requests.

filterstringOptional

Dashboard filters as one URL-encoded JSON object (maximum 16 KB). All conditions must match. See the schema for fields, operators, and value constraints.

Response

Successful response.
datalist of objects
Conversation webhook payloads for this page. Customer analytics and internal fields are excluded.
paginationobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error