Spans

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.

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

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

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

# 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

Inspect available span filter values and counts.

inf span facets

inf span facets accepts the same filters as 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

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

# 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

inf trace opens whole traces, trees, timelines, and trace exports.
inf inference inspects gateway request/response records.
inf dashboard launches the interactive terminal dashboard.

Get Started

Command Reference

`inf span list`

Options

Examples

`inf span get`

Arguments

Options

Views

Examples

`inf span facets`

Examples

Advanced filter syntax

Common workflows

​inf span list

​Options

​Examples

​inf span get

​Arguments

​Options

​Views

​Examples

​inf span facets

​Examples

​Advanced filter syntax

​Common workflows

​Related commands

`inf span list`

Options

Examples

`inf span get`

Arguments

Options

Views

Examples

`inf span facets`

Examples

Advanced filter syntax

Common workflows

Related commands