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

# Conversations

> Inspect monitored conversations, audio, and metric results with the Coval CLI

A **conversation** is a recorded interaction (voice call or chat) submitted to Coval for monitoring evaluation. Conversations are distinct from [simulations](/cli/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.

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

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

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

## List Conversations

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

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

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

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

## Download Audio

Download or get the audio URL for a conversation recording.

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

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

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

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

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

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

By Metric definition ID (one or more rows):

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

## Delete Conversation

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

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