Skip to main content
GET
/
v1
/
conversations
List conversations
curl --request GET \
  --url https://api.coval.dev/v1/conversations \
  --header 'X-API-Key: <api-key>'
{
  "conversations": [
    {
      "name": "conversations/gk3jK9mPq2xRt5vW8yZaBc",
      "conversation_id": "gk3jK9mPq2xRt5vW8yZaBc",
      "status": "COMPLETED",
      "create_time": "2025-11-03T14:32:30Z",
      "external_conversation_id": "external-call-7x8z9a",
      "occurred_at": "2025-11-03T14:32:00Z",
      "has_audio": true,
      "metadata": {
        "campaign": "q4-support"
      }
    },
    {
      "name": "conversations/hL4kL0nQr3ySt6vX9zAcDd",
      "conversation_id": "hL4kL0nQr3ySt6vX9zAcDd",
      "status": "IN_PROGRESS",
      "create_time": "2025-11-03T15:20:18Z",
      "external_conversation_id": "twilio-call-CA9m2k4p",
      "occurred_at": "2025-11-03T15:20:00Z",
      "has_audio": true,
      "metadata": {
        "department": "sales"
      }
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOiA1MH0="
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication.

Query Parameters

​
page_size
integer
default:50

Maximum number of conversations to return (1-250)

Required range: 1 <= x <= 250
​
page_token
string

Token for retrieving next page (from previous response)

​
filter
string

Filter expression syntax.

Operators: =, !=, >, <, >=, <=, AND, OR

Values may be unquoted or double-quoted. Values containing spaces must be quoted.

Fields:

  • status - PENDING, IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, DELETED
  • external_conversation_id - Your system's conversation ID
  • create_time - ISO 8601 timestamp
  • occurred_at - ISO 8601 timestamp
  • metadata.{key} - Custom metadata fields

Examples:

  • status=COMPLETED
  • create_time>"2025-11-01T00:00:00Z"
  • status=COMPLETED AND occurred_at>="2025-11-01T00:00:00Z"
  • external_conversation_id=external-call-abc
​
order_by
string
default:-occurred_at

Sort field with optional - prefix for descending order.

Fields: create_time, occurred_at, status

Examples:

  • create_time (ascending)
  • -create_time (descending, most recent first)
  • -occurred_at (most recent conversations first)

Response

List of conversations

​
conversations
object[]
required

List of conversations (max page_size items)

​
next_page_token
string | null

Token for retrieving next page.

null indicates last page. Pass this value in page_token query parameter for next page.

Example:

"eyJvZmZzZXQiOiA1MH0="