Skip to main content
GET
List conversations

Authorizations

Authorization
string
header
required

Send Authorization: Bearer YOUR_API_KEY. The key resolves to a single organization.

Query Parameters

agentId
string<uuid>

Filter to one agent.

meta
string

Conversation metadata property filters: key:op[:value], joined by ; (up to 8, all must match). key is a dotted path into the conversation metadata (e.g. campaign, model.provider). op is one of eq, neq, contains, not_contains, gt, gte, lt, lte (these take a URI-encoded value; the numeric ones need a number), or is_set, is_not_set, is_true, is_false. Example: campaign:eq:spring%20sale;score:gte:3. The same syntax as the dashboard's Conversations filter. A filter that does not parse returns 400. Nested property paths are discovered and indexed automatically. Example: contexto.call_id:eq:1234567890 finds the exact ID, including when metadata stores it as a JSON number. Selective exact-value filters (eq/neq) use the search index after historical coverage is verified; common values and other operators retain their existing JSON behavior.

referenceId
string

Exact match on the conversation's referenceId: the upstream call id your provider or your own system sent (for example a LiveKit room name). Served from an index, so it is the fast way to find one call by your own id, however old it is. Usually returns zero or one conversation; the same id can repeat across agents. An empty value returns 400.

Required string length: 1 - 255
createdAfter
string

Only conversations whose createdAt is at or after this instant (inclusive). An ISO 8601 date (2026-11-01, read as UTC midnight) or a date-time with a UTC offset (2026-11-01T14:30:00Z, 2026-11-01T11:30:00-03:00). At most millisecond precision. A date-time without an offset, a year outside 1900–2299, or any other format returns 400.

createdBefore
string

Only conversations whose createdAt is before this instant (exclusive). Same format as createdAfter, and must be later than it. Together they page one window, newest first, instead of everything newer than it.

limit
integer
default:50

Items per page. Default 50, max 200 (larger values are clamped to 200). Must be a positive integer; anything else is rejected with a 400 invalid_parameter.

Required range: 1 <= x <= 200
cursor
string

Opaque pagination cursor. Pass the nextCursor returned by the previous page, unchanged. A cursor this API did not issue is rejected with a 400 invalid_parameter. List endpoints also answer 400 unknown_query_parameter (listing the valid names) for any query parameter they do not accept, so a misspelled filter such as agent_id is never silently ignored.

Response

Page of conversations.

data
object[]
required
nextCursor
string | null
required