curl --request GET \
--url https://api.coval.dev/v1/conversations/simulated/{simulation_id}/metrics \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.coval.dev/v1/conversations/simulated/{simulation_id}/metrics"
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/{simulation_id}/metrics', 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/{simulation_id}/metrics",
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/{simulation_id}/metrics"
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/{simulation_id}/metrics")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/conversations/simulated/{simulation_id}/metrics")
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{
"metrics": [
{
"metric_output_id": "01JCQR8Z9PQSTNVWXY12345678",
"metric_id": "abc123xyz789",
"status": "COMPLETED",
"metric_version_ulid": "01JCQR8Z9PQSTNVWXY12345678",
"value": 0.85,
"status_reason": "No OTel trace spans were found for this simulation.",
"explanation": "The agent never confirmed the caller's address before ending the call.",
"evidence_references": [
{
"frame_id": "<string>",
"type": "frame"
}
],
"subvalues_by_timestamp": [
{
"start_offset": 0,
"end_offset": 2.5,
"output_type": "float",
"float_value": 0.85,
"string_value": "",
"role": "assistant",
"message_index": 3,
"metadata": {}
}
],
"result": {
"llm": {
"answer_explanation": "The agent never confirmed the caller's address before ending the call.",
"prompt": "Did the agent confirm the caller's address?"
}
},
"runtime_metadata": {},
"subvalues_by_timestamp_total_count": 0,
"subvalues_by_timestamp_truncated": false
}
],
"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": "NOT_FOUND",
"message": "Agent not found",
"details": [
{
"field": "agent_id",
"description": "Agent 'gk3jK9mPq2xRt5vW8yZaBc' does not exist"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred. Please contact support."
}
]
}
}List metrics
List metric results for a simulation.
Re-scoring a metric on a simulation appends a new output rather than replacing the
previous one. By default this endpoint returns only the most recent output for each
metric, so a metric appears at most once. Pass include_superseded=true to get the
full history, including outputs that a later re-score has replaced.
curl --request GET \
--url https://api.coval.dev/v1/conversations/simulated/{simulation_id}/metrics \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.coval.dev/v1/conversations/simulated/{simulation_id}/metrics"
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/{simulation_id}/metrics', 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/{simulation_id}/metrics",
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/{simulation_id}/metrics"
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/{simulation_id}/metrics")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/conversations/simulated/{simulation_id}/metrics")
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{
"metrics": [
{
"metric_output_id": "01JCQR8Z9PQSTNVWXY12345678",
"metric_id": "abc123xyz789",
"status": "COMPLETED",
"metric_version_ulid": "01JCQR8Z9PQSTNVWXY12345678",
"value": 0.85,
"status_reason": "No OTel trace spans were found for this simulation.",
"explanation": "The agent never confirmed the caller's address before ending the call.",
"evidence_references": [
{
"frame_id": "<string>",
"type": "frame"
}
],
"subvalues_by_timestamp": [
{
"start_offset": 0,
"end_offset": 2.5,
"output_type": "float",
"float_value": 0.85,
"string_value": "",
"role": "assistant",
"message_index": 3,
"metadata": {}
}
],
"result": {
"llm": {
"answer_explanation": "The agent never confirmed the caller's address before ending the call.",
"prompt": "Did the agent confirm the caller's address?"
}
},
"runtime_metadata": {},
"subvalues_by_timestamp_total_count": 0,
"subvalues_by_timestamp_truncated": false
}
],
"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": "NOT_FOUND",
"message": "Agent not found",
"details": [
{
"field": "agent_id",
"description": "Agent 'gk3jK9mPq2xRt5vW8yZaBc' does not exist"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred. Please contact support."
}
]
}
}Authorizations
API key for authentication.
Path Parameters
The simulation ID
22 - 27Query Parameters
Filter expression syntax.
Supported fields: status, metric_id, metric_name, value, create_time, start_time, end_time
Operators: =, !=, >, <, >=, <=, AND, OR
Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., status="IN PROGRESS").
Maximum number of results per page
1 <= x <= 1000Opaque pagination token from previous response
Response detail level. FULL preserves the historical response including
structured result and runtime_metadata; BASIC omits those heavy fields
while retaining value, status, explanation, and bounded subvalues.
BASIC, FULL Include outputs that a later re-score of the same metric has superseded.
When false (default) each metric contributes only its most recent output. When
true every output is returned, so one metric may appear multiple times; recency is
determined by creation time, with the metric_output_id ULID breaking ties, and the
response order still follows order_by.
Sort order specification.
Format: field or -field (descending)
Supported fields: metric_name, create_time, value, start_time, end_time
Was this page helpful?