> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inference.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> Browse trace trees, inspect trace facets, and manage trace exports from the CLI.

Use `inf trace` to inspect multi-step LLM workflows captured by Catalyst Tracing. It mirrors the dashboard trace viewer for headless debugging: list trace summaries, open a trace tree, render a timeline, inspect captured conversation messages, discover filter facets, and queue/download trace exports.

**Alias:** `inf traces`

## `inf trace upload`

Upload a JSONL trace file into the active project. The CLI validates the format locally (OTLP or Langfuse export), uploads it in parts, waits for processing to finish, and prints the upload ID plus line counts. Same flow as the dashboard **Upload** button and [`inf dataset upload`](/cli/datasets#inf-dataset-upload).

<Metadata text="cli/traces/upload" />

```bash theme={"system"}
inf trace upload <file>
```

### Arguments

| Argument | Required | Description                   |
| -------- | -------- | ----------------------------- |
| `file`   | Yes      | Path to a `.jsonl` trace file |

### Options

| Flag                | Required | Description                                                    | Default                    |
| ------------------- | -------- | -------------------------------------------------------------- | -------------------------- |
| `-n, --name <name>` | No       | Upload name shown in Catalyst                                  | Filename without extension |
| `--no-wait`         | No       | Return after the transfer completes without polling processing | Off                        |

Uploaded traces appear under the **Traces** tab once processing completes. Filter them with all-time range and the upload ID (`trace_import_id` in filters):

<Metadata text="cli/traces/upload-examples" />

```bash theme={"system"}
# Upload and wait for processing (default)
inf trace upload ./exports/langfuse-traces.jsonl

# Custom upload name
inf trace upload ./traces.jsonl --name prod-replay-2026-04-01

# Queue processing but do not wait
inf trace upload ./traces.jsonl --no-wait

# List traces from a completed upload
inf trace list --range all --filter "trace_import_id=<upload-id>"
```

## `inf trace list`

Display trace summaries in the active project.

<Metadata text="cli/traces/list" />

```bash theme={"system"}
inf trace list
```

**Alias:** `inf trace ls`

### Options

| Flag                   | Required | Description                                                                                       | Default          |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------- | ---------------- |
| `-l, --limit <n>`      | No       | Maximum number of traces                                                                          | `25`             |
| `--cursor <cursor>`    | No       | Pagination cursor from a previous response                                                        | -                |
| `--sort <key>`         | No       | Sort by `start_time`, `duration`, `total_cost`, `total_tokens`, `span_count`, or `llm_span_count` | Server default   |
| `--order <asc\|desc>`  | No       | Sort order                                                                                        | Server default   |
| `--range <preset>`     | No       | Relative time range: `1h`, `6h`, `12h`, `1d`, `3d`, `7d`, `14d`, `30d`, `90d`, `all`              | `1d`             |
| `--from <iso>`         | No       | Start time. Must be used with `--to`                                                              | -                |
| `--to <iso>`           | No       | End time. Must be used with `--from`                                                              | -                |
| `--kind <kind>`        | No       | Observation kind. Repeat or comma-separate values like `LLM,TOOL,AGENT`                           | All kinds        |
| `--provider <name>`    | No       | LLM provider filter                                                                               | All providers    |
| `--model <name>`       | No       | LLM model filter                                                                                  | All models       |
| `--service <name>`     | No       | OpenTelemetry `service.name` filter                                                               | All services     |
| `--environment <name>` | No       | Deployment environment filter                                                                     | All environments |
| `--user <id>`          | No       | User ID filter                                                                                    | All users        |
| `--session <id>`       | No       | Session ID filter                                                                                 | All sessions     |
| `--agent <name>`       | No       | Agent name filter                                                                                 | All agents       |
| `--status <ok\|error>` | No       | Trace status filter                                                                               | All statuses     |
| `--filter <expr>`      | No       | Advanced typed field filter. Repeatable                                                           | -                |
| `--metadata <expr>`    | No       | Span attribute filter. Repeatable                                                                 | -                |
| `--resource <expr>`    | No       | Resource attribute filter. Repeatable                                                             | -                |

Use `--json` for the raw API payload with full trace IDs, pagination cursors, and aggregate counts.

### Examples

<Metadata text="cli/traces/list-examples" />

```bash theme={"system"}
# Recent traces
inf trace list

# Failed LLM traces from the last hour
inf trace list --range 1h --kind LLM --status error

# Slow traces by duration, sorted longest first
inf trace list --filter "duration_ms>5000" --sort duration --order desc

# Filter by service and model
inf trace list --service api --model claude-sonnet-4-5
```

## `inf trace get`

Open a single trace and its spans.

<Metadata text="cli/traces/get" />

```bash theme={"system"}
inf trace get <trace-id>
```

**Alias:** `inf trace show`

### Arguments

| Argument   | Required | Description |
| ---------- | -------- | ----------- |
| `trace-id` | Yes      | Trace ID    |

### Options

| Flag                  | Required | Description                                                | Default   |
| --------------------- | -------- | ---------------------------------------------------------- | --------- |
| `--view <view>`       | No       | `summary`, `tree`, `timeline`, `thread`, `spans`, or `raw` | `summary` |
| `--span <span-id>`    | No       | Highlight a selected span in the tree view                 | -         |
| `--limit <n>`         | No       | Maximum spans to fetch for this trace                      | `1000`    |
| `--cursor <cursor>`   | No       | Span pagination cursor                                     | -         |
| `-o, --output <path>` | No       | Write raw JSON to a file                                   | -         |

The default summary view prints trace metadata and an ASCII span tree. Use `--view raw` or global `--json` when piping trace data into scripts.

### Examples

<Metadata text="cli/traces/get-examples" />

```bash theme={"system"}
# Summary plus span tree
inf trace get 2f0d2b...

# Text waterfall ordered by span start time
inf trace get 2f0d2b... --view timeline

# Conversation-style view from captured input/output messages
inf trace get 2f0d2b... --view thread

# Persist raw trace + spans JSON for local analysis
inf trace get 2f0d2b... --view raw -o trace.json
```

## `inf trace facets`

Inspect available trace filter values and counts. This is useful when building a repeatable query and you do not know the exact model, service, environment, or attribute values in a project.

<Metadata text="cli/traces/facets" />

```bash theme={"system"}
inf trace facets
```

### Options

`inf trace facets` accepts the same filter flags as [`inf trace list`](#inf-trace-list), plus:

| Flag                          | Required | Description                                               | Default              |
| ----------------------------- | -------- | --------------------------------------------------------- | -------------------- |
| `--facet <id>`                | No       | Facet ID. Repeat or comma-separate values                 | All supported facets |
| `--search <facet=query>`      | No       | Search within a facet's values. Repeatable                | -                    |
| `--attribute-key <scope:key>` | No       | Fetch values for one `span:` or `resource:` attribute key | -                    |
| `-l, --limit <n>`             | No       | Maximum options per facet                                 | `50`                 |

### Examples

<Metadata text="cli/traces/facets-examples" />

```bash theme={"system"}
# Show all default trace facets
inf trace facets --range 7d

# Find model facet values containing "claude"
inf trace facets --facet llm_model_name --search llm_model_name=claude

# Explore values for an OpenTelemetry span attribute
inf trace facets --attribute-key span:gen_ai.operation.name
```

## Advanced filter syntax

`--filter`, `--metadata`, and `--resource` are repeatable. Quote expressions so your shell does not interpret operators.

| Expression                              | Meaning                                                                                   |
| --------------------------------------- | ----------------------------------------------------------------------------------------- |
| `duration_ms>500`                       | Numeric comparison. `duration` and `duration_ms` are converted to nanoseconds for the API |
| `total_tokens between:100,500`          | Numeric range                                                                             |
| `span_count>=3`                         | Trace aggregate filter                                                                    |
| `llm_model_name~claude`                 | String contains                                                                           |
| `service_name in:api,worker`            | String set membership                                                                     |
| `agent_name not-empty`                  | Non-empty string field                                                                    |
| `--metadata gen_ai.operation.name=chat` | Span attribute equality                                                                   |
| `--resource service.version~2026`       | Resource attribute contains                                                               |

## `inf trace export`

Trace exports create downloadable JSONL files for offline analysis, support escalations, or long-running review workflows.

### `inf trace export create`

Queue an export job.

<Metadata text="cli/traces/export-create" />

```bash theme={"system"}
inf trace export create --range 7d --kind LLM
```

| Flag                               | Required | Description                               | Default               |
| ---------------------------------- | -------- | ----------------------------------------- | --------------------- |
| `--from <iso>` / `--to <iso>`      | No       | Explicit export window                    | -                     |
| `--range <preset>`                 | No       | Relative export window                    | `1d`                  |
| `--kind <kind>`                    | No       | Observation kind filter                   | All kinds             |
| `--trace-id <id>`                  | No       | Trace ID. Repeat or comma-separate values | -                     |
| `--session <id>`                   | No       | Session ID filter                         | -                     |
| `--user <id>`                      | No       | User ID filter                            | -                     |
| `--agent <name>`                   | No       | Agent name filter                         | -                     |
| `--model <name>`                   | No       | LLM model filter                          | -                     |
| `--status-code <OK\|ERROR\|UNSET>` | No       | Span status code filter                   | -                     |
| `--attribute <key=value>`          | No       | Attribute equality match. Repeatable      | -                     |
| `--wait`                           | No       | Poll until the export finishes            | Off                   |
| `--download`                       | No       | Download after the export is ready        | Off                   |
| `-o, --output <path>`              | No       | Download path                             | Generated from job ID |

<Metadata text="cli/traces/export-create-examples" />

```bash theme={"system"}
# Queue and print a job ID
inf trace export create --range 30d --kind LLM

# Queue, wait, and download in one command
inf trace export create --range 7d --status-code ERROR --wait --download -o failed-traces.jsonl
```

### `inf trace export list`

<Metadata text="cli/traces/export-list" />

```bash theme={"system"}
inf trace export list
```

### `inf trace export status`

<Metadata text="cli/traces/export-status" />

```bash theme={"system"}
inf trace export status <job-id>
```

### `inf trace export download`

<Metadata text="cli/traces/export-download" />

```bash theme={"system"}
inf trace export download <job-id> -o traces.jsonl
```

## Related commands

* [`inf span`](/cli/spans) lists and opens individual spans.
* [`inf inference`](/cli/inferences) inspects gateway request/response records.
* [`inf dashboard`](/cli/dashboard) launches the interactive terminal dashboard.