Uploaded Conversations

An uploaded conversation is a production voice call or chat submitted to Coval for evaluation. Uploaded conversations are distinct from simulated conversations, which Coval creates during a run. submit also accepts --input-json (inline JSON, @file, or - for stdin); explicit flags override fields from the JSON. See Input JSON.

Submit Conversation

Submit a production conversation for evaluation. At least one input source is required (--transcript-file, --audio-file, --audio-url, or --upload-id); audio sources are mutually exclusive.

coval uploaded-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 organization’s uploaded-conversation 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.
`--tag`	string	Tag to apply to the conversation. Repeat for multiple.

Returns the created conversation in PENDING status. Poll coval uploaded-conversations get <id> to watch evaluation progress.

# Submit a transcript with custom metrics and metadata
coval uploaded-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 \
  --tag summer-campaign \
  --tag escalation

# Submit audio by presigned URL
coval uploaded-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 uploaded-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 Uploaded Conversations

coval uploaded-conversations list [OPTIONS]

Option	Type	Default	Description
`--filter`	string	—	Filter expression
`--page-size`	number	50	Results per page
`--order-by`	string	—	Sort order
`--include-metric-outputs`	string	—	Metric ID; include that metric’s full outputs on every conversation in the page

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

# List recent conversations
coval uploaded-conversations list

# Filter by status
coval uploaded-conversations list --filter 'status="COMPLETED"'

# Filter by external ID
coval uploaded-conversations list --filter 'external_conversation_id="call-abc-123"'

# Include one metric's outputs alongside each conversation
coval uploaded-conversations list --include-metric-outputs 29BlkepvvX19ebbLDB0y6Q --format json

Get Uploaded Conversation

coval uploaded-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 uploaded-conversations get conv_abc123

Patch Uploaded Conversation

Attach audio to an existing conversation or add metadata keys. Metadata is additive only: the API rejects a key that already has a value.

coval uploaded-conversations patch <conversation_id> [OPTIONS]

Argument	Type	Required	Description
`conversation_id`	string	Yes	The conversation ID to patch

Option	Type	Description
`--audio-url`	string	Presigned URL to audio to attach
`--audio-file`	path	Local audio file to attach
`--metadata`	`key=value`	Metadata to add. Repeat for multiple. Existing keys cannot be overwritten

# Add metadata after the fact
coval uploaded-conversations patch conv_abc123 \
  --metadata resolution=refunded \
  --metadata csat=4

# Attach a recording to a transcript-only conversation
coval uploaded-conversations patch conv_abc123 --audio-url 'https://bucket.example.com/audio.wav?signature=...'

Download Audio

Download or get the audio URL for a conversation recording.

coval uploaded-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 uploaded-conversations audio conv_abc123

# Download audio file
coval uploaded-conversations audio conv_abc123 -o recording.wav

When using -o, a progress bar shows the download status.

List Metrics

List the current metric results for an uploaded conversation. If a metric has been re-scored, only its most recent result is listed.

coval uploaded-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 uploaded-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 uploaded-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 uploaded-conversations metric-detail conv_abc123 01JCQR8Z9PQSTNVWXY12345678

By Metric definition ID (one or more rows):

coval uploaded-conversations metric-detail conv_abc123 4HTX6gnqXtpexWSLNaKdC4

Delete Conversation

coval uploaded-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 Uploaded Conversations

Get Uploaded Conversation

Patch Uploaded Conversation

Download Audio

List Metrics

Get Metric Detail

Delete Conversation

Conversation Statuses

​Submit Conversation

​List Uploaded Conversations

​Get Uploaded Conversation

​Patch Uploaded Conversation

​Download Audio

​List Metrics

​Get Metric Detail

​Delete Conversation

​Conversation Statuses

Submit Conversation

List Uploaded Conversations

Get Uploaded Conversation

Patch Uploaded Conversation

Download Audio

List Metrics

Get Metric Detail

Delete Conversation

Conversation Statuses