curl --request GET \
--url https://api.coval.dev/v1/conversations/simulated \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.coval.dev/v1/conversations/simulated"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.coval.dev/v1/conversations/simulated', 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/simulated",
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/simulated"
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))
}HttpResponse<String> response = Unirest.get("https://api.coval.dev/v1/conversations/simulated")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/conversations/simulated")
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{
"simulated_conversations": [
{
"name": "simulations/abc123xyz789",
"simulation_id": "abc123xyz789",
"run_id": "abc123xyz789",
"status": "COMPLETED",
"create_time": "2025-10-14T12:00:00Z",
"has_audio": true,
"agent_id": "gk3jK9mPq2xRt5vW8yZaBc",
"persona_id": "hL4kL0nQr3ySt6vX9zAcDd",
"test_set_id": "aB1cD2eF",
"test_case_id": "test_xyz123",
"source": {
"type": "phone",
"value": "+15551234567"
},
"destination": {
"type": "phone",
"value": "+15551234567"
},
"error_message": "Simulation failed to run.",
"mutation_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"mutation_name": "GPT-4 Fast VAD",
"notes": "Reviewed – false positive",
"is_public": false,
"metric_values": {
"29BlkepvvX19ebbLDB0y6Q": 0.92
}
}
],
"next_page_token": "eyJvZmZzZXQiOiA1MH0="
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Request validation failed",
"details": [
{
"field": "iteration_count",
"description": "Value must be between 1 and 10"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Missing API Key",
"details": [
{
"field": "X-API-Key",
"description": "X-API-Key header is required"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred. Please contact support."
}
]
}
}List simulations
List simulations with optional filtering and sorting.
curl --request GET \
--url https://api.coval.dev/v1/conversations/simulated \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.coval.dev/v1/conversations/simulated"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.coval.dev/v1/conversations/simulated', 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/simulated",
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/simulated"
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))
}HttpResponse<String> response = Unirest.get("https://api.coval.dev/v1/conversations/simulated")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/conversations/simulated")
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{
"simulated_conversations": [
{
"name": "simulations/abc123xyz789",
"simulation_id": "abc123xyz789",
"run_id": "abc123xyz789",
"status": "COMPLETED",
"create_time": "2025-10-14T12:00:00Z",
"has_audio": true,
"agent_id": "gk3jK9mPq2xRt5vW8yZaBc",
"persona_id": "hL4kL0nQr3ySt6vX9zAcDd",
"test_set_id": "aB1cD2eF",
"test_case_id": "test_xyz123",
"source": {
"type": "phone",
"value": "+15551234567"
},
"destination": {
"type": "phone",
"value": "+15551234567"
},
"error_message": "Simulation failed to run.",
"mutation_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"mutation_name": "GPT-4 Fast VAD",
"notes": "Reviewed – false positive",
"is_public": false,
"metric_values": {
"29BlkepvvX19ebbLDB0y6Q": 0.92
}
}
],
"next_page_token": "eyJvZmZzZXQiOiA1MH0="
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Request validation failed",
"details": [
{
"field": "iteration_count",
"description": "Value must be between 1 and 10"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Missing API Key",
"details": [
{
"field": "X-API-Key",
"description": "X-API-Key header is required"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred. Please contact support."
}
]
}
}Authorizations
API key for authentication.
Query Parameters
Filter expression syntax.
Supported fields: status, agent_id, persona_id, test_set_id, test_case_id, run_id, external_conversation_id, mutation_id, mutation_name, create_time, metric.{metric_id}
Operators: =, !=, >, <, >=, <=, AND, OR
A metric.{metric_id} predicate (score filtering; number and string metrics, type inferred
from the literal) returns only simulations whose metric matches, with each simulation's value
per metric embedded inline (metric_values). On this path the request is keyset-paginated,
ordered newest-first by creation time, and supports only AND alongside create_time,
agent_id, status, test_set_id, and persona_id; other fields and any non-default
order_by are rejected with 400, and page_size is capped at 100.
Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., status="IN PROGRESS").
The external_conversation_id field is your system's conversation ID for cross-system lookup.
Mutation Filtering: Use mutation_id or mutation_name to filter simulations by agent mutation variant.
Base agent simulations have both mutation_id and mutation_name = null.
To get only base agent results, filter for simulations where mutation_id is not set.
Maximum number of results per page
1 <= x <= 1000Opaque pagination token from previous response
Sort order specification.
Format: field or -field (descending)
Supported fields: create_time, status
Set to metric_values to embed each simulation's value per metric inline. Served by the
keyset engine (newest-first, page_size capped at 100).
metric_values Was this page helpful?