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.
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 list
Display trace summaries in the active project.
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 | - |
--json for the raw API payload with full trace IDs, pagination cursors, and aggregate counts.
Examples
# 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.
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 | - |
--view raw or global --json when piping trace data into scripts.
Examples
# 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.
Options
inf trace facets accepts the same filter flags as 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
# 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.
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 |
# 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
inf trace export status
inf trace export status <job-id>
inf trace export download
inf trace export download <job-id> -o traces.jsonl
