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

# Spans

> Search spans, inspect span payloads, and debug trace steps from the CLI.

Use `inf span` when you already know you need span-level detail instead of a whole trace tree. It lets you search spans across traces, focus on root or entrypoint spans, inspect captured input/output, and print OpenTelemetry attributes for a single step.

**Alias:** `inf spans`

## `inf span list`

Display spans in the active project.

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

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

**Alias:** `inf span ls`

### Options

| Flag                              | Required | Description                                                                          | Default          |
| --------------------------------- | -------- | ------------------------------------------------------------------------------------ | ---------------- |
| `-l, --limit <n>`                 | No       | Maximum number of spans                                                              | `25`             |
| `--cursor <cursor>`               | No       | Pagination cursor from a previous response                                           | -                |
| `--sort <key>`                    | No       | Sort by `start_time`, `duration_ns`, `cost_total`, or `total_tokens`                 | Server default   |
| `--order <asc\|desc>`             | No       | Sort order                                                                           | Server default   |
| `--trace-id <id>`                 | No       | Limit results to one trace                                                           | -                |
| `--text <query>`                  | No       | Search captured span input/output text                                               | -                |
| `--scope <all\|root\|entrypoint>` | No       | Span scope filter                                                                    | `all`            |
| `--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       | Span 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` to preserve full trace IDs and span IDs for scripting.

### Examples

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

```bash theme={"system"}
# Recent spans
inf span list

# Root spans for failed traces in the last day
inf span list --scope root --status error --range 1d

# Spans inside a specific trace
inf span list --trace-id 2f0d2b...

# Search captured IO text for a string
inf span list --text "rate limit"

# Find expensive model spans
inf span list --kind LLM --filter "cost_total>0.05" --sort cost_total --order desc
```

## `inf span get`

Open a single span by trace ID and span ID.

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

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

**Alias:** `inf span show`

### Arguments

| Argument   | Required | Description                  |
| ---------- | -------- | ---------------------------- |
| `trace-id` | Yes      | Trace ID containing the span |
| `span-id`  | Yes      | Span ID                      |

### Options

| Flag                  | Required | Description                                                | Default   |
| --------------------- | -------- | ---------------------------------------------------------- | --------- |
| `--view <view>`       | No       | `summary`, `io`, `attributes`, `events`, `links`, or `raw` | `summary` |
| `-o, --output <path>` | No       | Write raw JSON to a file                                   | -         |

### Views

| View         | Use it for                                                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `summary`    | Span identity, timing, status, model/provider, token counts, cost, task/session metadata, and domain-specific summary fields |
| `io`         | Captured input, output, input messages, output messages, and retrieval documents                                             |
| `attributes` | Span and resource attributes across string, integer, and floating-point maps                                                 |
| `events`     | Raw OpenTelemetry events JSON                                                                                                |
| `links`      | Raw OpenTelemetry links JSON                                                                                                 |
| `raw`        | Full span JSON exactly as returned by the API                                                                                |

### Examples

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

```bash theme={"system"}
# Human-readable summary
inf span get 2f0d2b... 91f8c4...

# Inspect captured prompt/response payloads
inf span get 2f0d2b... 91f8c4... --view io

# Inspect OpenTelemetry attributes
inf span get 2f0d2b... 91f8c4... --view attributes

# Save raw span JSON
inf span get 2f0d2b... 91f8c4... --view raw -o span.json
```

## `inf span facets`

Inspect available span filter values and counts.

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

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

`inf span facets` accepts the same filters as [`inf span list`](#inf-span-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/spans/facets-examples" />

```bash theme={"system"}
# Discover span facets for recent traffic
inf span facets --range 1d

# Search model facet values
inf span facets --facet llm_model_name --search llm_model_name=claude

# List values for a span attribute
inf span facets --attribute-key span:gen_ai.operation.name
```

## Advanced filter syntax

The span filter language matches [`inf trace`](/cli/traces) except trace aggregate fields such as `span_count` and `llm_span_count` are not valid for span queries.

| 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_name~retrieval`                   | String contains                                                                           |
| `llm_provider=anthropic`                | String equality                                                                           |
| `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                                                               |

## Common workflows

<Metadata text="cli/spans/workflows" />

```bash theme={"system"}
# Pick a trace, then inspect its LLM spans
TRACE_ID=$(inf trace list --json | jq -r '.traces[0].traceId')
inf span list --trace-id "$TRACE_ID" --kind LLM --json

# Open the first span from that trace
SPAN_ID=$(inf span list --trace-id "$TRACE_ID" --json | jq -r '.spans[0].spanId')
inf span get "$TRACE_ID" "$SPAN_ID" --view io
```

## Related commands

* [`inf trace`](/cli/traces) opens whole traces, trees, timelines, and trace exports.
* [`inf inference`](/cli/inferences) inspects gateway request/response records.
* [`inf dashboard`](/cli/dashboard) launches the interactive terminal dashboard.