List conversations

curl --request GET \
  --url https://api.coval.dev/v1/conversations \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.coval.dev/v1/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.coval.dev/v1/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.coval.dev/v1/conversations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.coval.dev/v1/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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="
}

GET

conversations

List conversations

curl --request GET \
  --url https://api.coval.dev/v1/conversations \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.coval.dev/v1/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.coval.dev/v1/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.coval.dev/v1/conversations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.coval.dev/v1/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
metric.{metric_id} - Filter by a metric's value (score filtering)

Metric-value filtering: a metric.{metric_id} predicate (e.g. metric.29Blkepvvx<"0.9"; >/</>=/<=/=/!= for float metrics, =/!= for string metrics) returns only conversations whose metric matches, with every metric's value embedded inline (metric_values). The metric type is inferred from the literal — a numeric literal is compared as a float metric. When a metric predicate is present the request is served with keyset pagination, ordered newest-first by creation time, and supports only AND alongside create_time (inclusive bounds), agent_id, and metadata.{key}; other filter fields (including occurred_at) and any non-default order_by are rejected with 400, and page_size is capped at 100.

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
metric.29BlkepvvX19ebbLDB0y6Q<"0.5"

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)

view

enum<string>

Set to metric_breakdown to return an aggregate of one metric's scores grouped by a customer_metadata key (e.g. vendor), computed over the whole scored monitoring corpus, instead of the conversation list. Requires metric_id and group_by_metadata; the response is a metric-breakdown object ({view, metric_id, group_by_metadata, aggregation, breakdown:[{metadata_value, value, count}], total_count}).

Available options:

metric_breakdown

metric_id

string

Metric to aggregate when view=metric_breakdown, or the metric whose full outputs should be embedded when include=metric_outputs.

include

enum<string>

Set to metric_outputs to embed full outputs for metric_id on every conversation in the returned page, or metric_values to embed every metric's value inline on each conversation (keyset-paginated; page_size capped at 100). Omitted by default to keep list payloads small.

Available options:

metric_outputs,

metric_values

group_by_metadata

string

Required when view=metric_breakdown: the customer_metadata key to group by (e.g. nlp_provider).

aggregation

enum<string>

Aggregation for view=metric_breakdown. Defaults to success (a YES/NO success rate) for binary/string metrics and avg (numeric mean) for float metrics.

Available options:

success,

avg

start_date

string<date-time>

Optional ISO-8601 lower bound (occurred_at) for view=metric_breakdown.

end_date

string<date-time>

Optional ISO-8601 upper bound (occurred_at) for view=metric_breakdown.

Response

List of conversations, or a metric breakdown when view=metric_breakdown

Option 1
Option 2

conversations

object[]

required

List of conversations (max page_size items)

Show child attributes

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

⌘I

API

Runs

Simulations

Conversations

Agents

Mutations

Test Sets

Test Cases

Personas

Metrics

Run Templates

Scheduled Runs

Reviews

Dashboards

Alerts

Reports

Tags

Webhooks

Traces

Conversations Config

API Keys

Integrations

List conversations

Authorizations

Query Parameters

Response