Conversations

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.

Returns the created conversation in 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 request body is capped at 10 MB. Those routes carry audio out of band and accept up to 250 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

Output columns: ID, STATUS, EXTERNAL ID, AUDIO, OCCURRED AT

# 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

Returns full conversation details as JSON including transcript, status, agent and persona references, progress, and metadata.

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

When using -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

Output columns: OUTPUT ID, METRIC ID, STATUS, VALUE, SUBVALUES

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

By MetricOutput ULID (one row):

coval conversations metric-detail conv_abc123 01JCQR8Z9PQSTNVWXY12345678

By Metric definition ID (one or more rows):

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").

Getting Started

Resources

Submit Conversation

List Conversations

Get Conversation

Download Audio

List Metrics

Get Metric Detail

Delete Conversation

Conversation Statuses

​Submit Conversation

​List Conversations

​Get Conversation

​Download Audio

​List Metrics

​Get Metric Detail

​Delete Conversation

​Conversation Statuses

Submit Conversation

List Conversations

Get Conversation

Download Audio

List Metrics

Get Metric Detail

Delete Conversation

Conversation Statuses