Documentation Index
Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
Use this file to discover all available pages before exploring further.
A conversation is a recorded interaction (voice call or chat) submitted to Coval for monitoring evaluation. Conversations are distinct from simulations, which are synthetic test runs generated by Coval.
Submit Conversation
Submit a recorded conversation for monitoring evaluation. At least one input source is required (--transcript-file, --audio-file, --audio-url, or --upload-id); audio sources are mutually exclusive.
coval conversations submit [OPTIONS]
| Option | Type | Description |
|---|
--transcript-file | path | JSON file containing the transcript (an array of message objects). |
--audio-file | path | Local audio file. The CLI base64-encodes the bytes into the request body. |
--audio-url | string | Presigned URL to audio (S3, GCS, Azure Blob, or any HTTPS URL). |
--upload-id | string | Reference to a prior POST /v1/audio:upload (upl_<26-char ULID>). |
--metric | string | Metric ID to evaluate. Repeat for multiple. Defaults to your org’s monitoring metrics. |
--metadata | key=value | Custom metadata for filtering and conditional metrics. Repeat for multiple. |
--external-id | string | External conversation ID from your system. |
--agent-id | string | Agent to associate with this conversation (22-char ID). |
--occurred-at | ISO 8601 | When the conversation actually occurred. |
PENDING status. Poll coval conversations get <id> to watch evaluation progress.
# Submit a transcript with custom metrics and metadata
coval conversations submit \
--transcript-file ./call.json \
--metric 29BlkepvvX19ebbLDB0y6Q \
--metric mymKvEg6ZA65srXbTX5wSM \
--metadata campaign=summer-2026 \
--metadata customer_id=cust-abc-123 \
--external-id call-abc-123 \
--agent-id gk3jK9mPq2xRt5vW8yZaBc \
--occurred-at 2026-05-05T12:34:56Z
# Submit audio by presigned URL
coval conversations submit \
--audio-url 'https://bucket.s3.amazonaws.com/audio.wav?X-Amz-Algorithm=...' \
--external-id call-abc-123
# Submit a local audio file (base64-encoded into the request body)
coval conversations submit --audio-file ./recording.wav --external-id call-abc-123
For audio files larger than a few megabytes, prefer --audio-url or --upload-id over --audio-file — the API Gateway request body is capped at 10 MB.
List Conversations
coval conversations list [OPTIONS]
| Option | Type | Default | Description |
|---|
--filter | string | — | Filter expression |
--page-size | number | 50 | Results per page |
--order-by | string | — | Sort order |
# List recent conversations
coval conversations list
# Filter by status
coval conversations list --filter 'status="COMPLETED"'
# Filter by external ID
coval conversations list --filter 'external_conversation_id="call-abc-123"'
Get Conversation
coval conversations get <conversation_id>
| Argument | Type | Required | Description |
|---|
conversation_id | string | Yes | The conversation ID |
coval conversations get conv_abc123
Download Audio
Download or get the audio URL for a conversation recording.
coval conversations audio <conversation_id> [OPTIONS]
| Argument | Type | Required | Description |
|---|
conversation_id | string | Yes | The conversation ID |
| Option | Type | Description |
|---|
-o, --output | string | File path to save audio |
# Print audio URL
coval conversations audio conv_abc123
# Download audio file
coval conversations audio conv_abc123 -o recording.wav
-o, a progress bar shows the download status.
List Metrics
List all metric results for a conversation.
coval conversations metrics <conversation_id>
| Argument | Type | Required | Description |
|---|
conversation_id | string | Yes | The conversation ID |
coval conversations metrics conv_abc123
Get Metric Detail
Retrieve metric results for a conversation. The second argument accepts two ID types and the output adapts accordingly:
- 26-char MetricOutput ULID — prints one row (the specific output).
- 22-char Metric definition ID — prints every output recorded for that metric on the conversation.
coval conversations metric-detail <conversation_id> <id>
| Argument | Type | Required | Description |
|---|
conversation_id | string | Yes | The conversation ID |
id | string | Yes | Either a 26-char MetricOutput ULID or a 22-char Metric definition ID |
coval conversations metric-detail conv_abc123 01JCQR8Z9PQSTNVWXY12345678
coval conversations metric-detail conv_abc123 4HTX6gnqXtpexWSLNaKdC4
Delete Conversation
coval conversations delete <conversation_id>
| Argument | Type | Required | Description |
|---|
conversation_id | string | Yes | The conversation ID to delete |
Conversation Statuses
| Status | Description |
|---|
PENDING | Conversation is created but not yet started |
IN_QUEUE | Conversation is queued for evaluation |
IN_PROGRESS | Metrics are actively running against the conversation |
COMPLETED | Evaluation finished successfully |
FAILED | Evaluation encountered an error |
CANCELLED | Evaluation was cancelled |
DELETED | Conversation was deleted |
When using --filter, use the underscore-separated enum values (e.g., status="IN_PROGRESS").
