> ## 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.

# Uploaded Conversations

> Submit and inspect production conversations with the Coval CLI

An **uploaded conversation** is a production voice call or chat submitted to Coval for evaluation. Uploaded conversations are distinct from [simulated conversations](/cli/simulated-conversations), which Coval creates during a run.

## 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.

```bash theme={null}
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.                                                                   |

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

```bash theme={null}
# 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

# 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
```

<Info>
  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.
</Info>

## List Uploaded Conversations

```bash theme={null}
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        |

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

```bash theme={null}
# 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"'
```

## Get Uploaded Conversation

```bash theme={null}
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.

```bash theme={null}
coval uploaded-conversations get conv_abc123
```

## Download Audio

Download or get the audio URL for a conversation recording.

```bash theme={null}
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 |

```bash theme={null}
# 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 all metric results for a conversation.

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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):

```bash theme={null}
coval uploaded-conversations metric-detail conv_abc123 01JCQR8Z9PQSTNVWXY12345678
```

By Metric definition ID (one or more rows):

```bash theme={null}
coval uploaded-conversations metric-detail conv_abc123 4HTX6gnqXtpexWSLNaKdC4
```

## Delete Conversation

```bash theme={null}
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                              |

<Info>
  When using `--filter`, use the underscore-separated enum values (e.g., `status="IN_PROGRESS"`).
</Info>