Check out the newest way to compare different models for a task/agent harness: AutoEvals

Command Reference

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.

inf span list

Alias: inf span ls

Options

FlagRequiredDescriptionDefault
-l, --limit <n>NoMaximum number of spans25
--cursor <cursor>NoPagination cursor from a previous response-
--sort <key>NoSort by start_time, duration_ns, cost_total, or total_tokensServer default
--order <asc|desc>NoSort orderServer default
--trace-id <id>NoLimit results to one trace-
--text <query>NoSearch captured span input/output text-
--scope <all|root|entrypoint>NoSpan scope filterall
--range <preset>NoRelative time range: 1h, 6h, 12h, 1d, 3d, 7d, 14d, 30d, 90d, all1d
--from <iso>NoStart time. Must be used with --to-
--to <iso>NoEnd time. Must be used with --from-
--kind <kind>NoObservation kind. Repeat or comma-separate values like LLM,TOOL,AGENTAll kinds
--provider <name>NoLLM provider filterAll providers
--model <name>NoLLM model filterAll models
--service <name>NoOpenTelemetry service.name filterAll services
--environment <name>NoDeployment environment filterAll environments
--user <id>NoUser ID filterAll users
--session <id>NoSession ID filterAll sessions
--agent <name>NoAgent name filterAll agents
--status <ok|error>NoSpan status filterAll statuses
--filter <expr>NoAdvanced typed field filter. Repeatable-
--metadata <expr>NoSpan attribute filter. Repeatable-
--resource <expr>NoResource attribute filter. Repeatable-

Use --json to preserve full trace IDs and span IDs for scripting.

Spans are retained for 60 days. 90d and all still return at most the last 60 days of history. Older span history is not available. See Data Retention.

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

ArgumentRequiredDescription
trace-idYesTrace ID containing the span
span-idYesSpan ID

Options

FlagRequiredDescriptionDefault
--view <view>Nosummary, io, attributes, events, links, or rawsummary
-o, --output <path>NoWrite raw JSON to a file-

Views

ViewUse it for
summarySpan identity, timing, status, model/provider, token counts, cost, task/session metadata, and domain-specific summary fields
ioCaptured input, output, input messages, output messages, and retrieval documents
attributesSpan and resource attributes across string, integer, and floating-point maps
eventsRaw OpenTelemetry events JSON
linksRaw OpenTelemetry links JSON
rawFull 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

inf span facets

Inspect available span filter values and counts.

inf span facets

inf span facets accepts the same filters as inf span list, plus:

FlagRequiredDescriptionDefault
--facet <id>NoFacet ID. Repeat or comma-separate valuesAll supported facets
--search <facet=query>NoSearch within a facet's values. Repeatable-
--attribute-key <scope:key>NoFetch values for one span: or resource: attribute key-
-l, --limit <n>NoMaximum options per facet50

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.

ExpressionMeaning
duration_ms>500Numeric comparison. duration and duration_ms are converted to nanoseconds for the API
total_tokens between:100,500Numeric range
span_name~retrievalString contains
llm_provider=anthropicString equality
service_name in:api,workerString set membership
agent_name not-emptyNon-empty string field
--metadata gen_ai.operation.name=chatSpan attribute equality
--resource service.version~2026Resource 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.

On this page