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

# Traces

> Search and inspect OpenTelemetry traces with the Coval CLI

When your agent sends OpenTelemetry traces to Coval, each simulated or uploaded conversation carries its spans. These commands search across spans, summarize one conversation's trace, and dump raw spans.

`search` also accepts `--input-json` (inline JSON, `@file`, or `-` for stdin) for the full filter object; explicit flags override fields from the JSON. See [Input JSON](/cli/agent-mode#input-json).

## Search Traces

Search spans across conversations and return the matching conversations.

```bash theme={null}
coval traces search [OPTIONS]
```

| Option               | Type     | Default | Description                                                                   |
| -------------------- | -------- | ------- | ----------------------------------------------------------------------------- |
| `--start-date`       | ISO 8601 | —       | Include spans at or after this timestamp                                      |
| `--end-date`         | ISO 8601 | —       | Include spans at or before this timestamp                                     |
| `--span-name`        | string   | —       | Case-insensitive substring match on span name                                 |
| `--provider`         | string   | —       | Case-insensitive substring match on provider                                  |
| `--status`           | string   | —       | Match span status: `error`, `ok`, or `unset`                                  |
| `--attribute-filter` | string   | —       | Attribute filter as `KEY:OPERATOR[:VALUE]`; repeat up to 10 times (see below) |
| `--duration-ms-min`  | number   | —       | Minimum span duration in milliseconds                                         |
| `--duration-ms-max`  | number   | —       | Maximum span duration in milliseconds                                         |
| `--agent-id`         | string   | —       | Restrict results to one agent                                                 |
| `--test-set-id`      | string   | —       | Restrict results to one test set                                              |
| `--sort-by`          | string   | —       | Result ordering: `newest`, `oldest`, `slowest`, or `fastest`                  |
| `--limit`            | number   | 25      | Results per page (1-100)                                                      |
| `--cursor`           | string   | —       | Opaque `next_cursor` from a previous search response                          |

### Attribute filters

`--attribute-filter` takes `KEY:OPERATOR[:VALUE]`. Supported operators:

| Operator                 | Meaning                      | Takes a value |
| ------------------------ | ---------------------------- | ------------- |
| `eq`                     | Attribute equals the value   | Yes           |
| `contains`               | Attribute contains the value | Yes           |
| `gt`, `gte`, `lt`, `lte` | Numeric comparison           | Yes           |
| `exists`                 | Attribute is present         | No            |

**Output columns:** Simulation Output, Run, Status, Matched / Total, Errors, Span Names, Providers

```bash theme={null}
# Slow tool calls in the last day
coval traces search \
  --start-date 2026-09-15T00:00:00Z \
  --span-name tool \
  --duration-ms-min 2000 \
  --sort-by slowest

# Spans that errored for one agent, with a specific attribute
coval traces search \
  --agent-id ag_abc123 \
  --status error \
  --attribute-filter 'tool.name:eq:lookup_order' \
  --attribute-filter 'retry.count:exists'
```

## Trace Summary

Summarize the trace data received for one conversation: span names and counts, timing and status distributions, structural integrity checks, and attribute key/type coverage. The summary never includes attribute values, prompt text, or tool arguments and results.

```bash theme={null}
coval traces summary [OPTIONS]
```

| Option              | Type   | Description                         |
| ------------------- | ------ | ----------------------------------- |
| `--simulation-id`   | string | Simulated conversation to summarize |
| `--conversation-id` | string | Uploaded conversation to summarize  |

Pass exactly one of the two IDs.

```bash theme={null}
coval traces summary --simulation-id sim_abc123
```

## Raw Spans

Return the raw spans recorded for a simulated conversation.

```bash theme={null}
coval traces spans <simulation_output_id> [OPTIONS]
```

| Argument               | Type   | Required | Description                                  |
| ---------------------- | ------ | -------- | -------------------------------------------- |
| `simulation_output_id` | string | **Yes**  | Simulated conversation whose spans to return |

| Option     | Type   | Default | Description                        |
| ---------- | ------ | ------- | ---------------------------------- |
| `--limit`  | number | 50      | Maximum spans to return (1-200)    |
| `--offset` | number | 0       | Number of spans to skip (0-100000) |

```bash theme={null}
coval traces spans sim_abc123 --limit 200 --format json
```