Command Reference
Inferences
List, filter, sort, and export inference requests and responses captured by Gateway.
Inspect inference requests and responses captured by Gateway. List and filter inferences in the active project, sort by tokens / cost / latency, discover the available filter values, and fetch the complete stored request and response bodies.
Alias: inf inferences
inf inference list
List and filter inferences in the active project.
inf inference listAlias: inf inference ls
Options
| Flag | Required | Description | Default |
|---|---|---|---|
-l, --limit <n> | No | Maximum number of results (1–100) | 20 |
--sort <key> | No | Sort key: sent_at, http_code, cost, duration, tokens, input_tokens, output_tokens, input_size, output_size | sent_at |
--order <asc|desc> | No | Sort order | desc |
--filter <expr> | No | Numeric filter <field><op><number> (repeatable). Fields: inputTokens, outputTokens, inputSizeBytes, outputSizeBytes, durationMs, totalCost. Ops: > >= < <= = != | — |
--metadata <expr> | No | Metadata filter <key><op><value> (repeatable). Ops: = != ~ !~, plus <key> is_empty / <key> is_not_empty | — |
-m, --model <name> | No | Filter by model (repeatable or comma-separated) | All models |
--provider <name> | No | Filter by downstream provider (repeatable or comma-separated) | All |
--environment <name> | No | Filter by environment (repeatable or comma-separated) | All |
--status <code> | No | Filter by HTTP status code, e.g. 200,500 (repeatable or comma-separated) | All |
--task <id> | No | Filter by task ID — matches the x-inference-task-id header set by inf instrument --task-id (repeatable or comma-separated) | — |
--upload <id> | No | Filter by upload ID (repeatable or comma-separated) | — |
--stream <bool> | No | Filter by streamed responses (true / false) | — |
--from <iso> / --to <iso> | No | Absolute time range (ISO-8601). Use both together. | — |
--range <preset> | No | Relative time range: 1h, 6h, 12h, 1d, 3d, 7d, 14d, 30d, 90d, all | — |
--cursor <cursor> | No | Pagination cursor (from a previous --json response) | — |
Don't hardcode filter values — run inf inference facets to discover the valid models, providers, environments, tasks, and metadata keys for the active project, along with the full filter reference.
The human-readable table shows the inference ID, model, status code (color-coded), input/output token counts, latency, cost, and timestamp. Add the global --json flag to emit the full result object — { items, nextCursor, hasMore, totalCount } — so scripts can read .items and paginate by passing .nextCursor back via --cursor.
Examples
# List the 10 most recent inferences
inf inference list --limit 10
# Largest-input requests first — e.g. find prompts over 39k tokens
inf inference list --sort input_tokens --order desc --limit 50
inf inference list --filter inputTokens>39000
# Combine numeric, array, and metadata filters over a time window
inf inference list --model meta-llama/llama-3.1-8b-instruct/fp-8 --status 200 --range 7d
inf inference list --filter durationMs>5000 --metadata user_id=abc123
# Paginate from a script — JSON output includes nextCursor
cursor=$(inf --json inference list --sort input_tokens --order desc | jq -r '.nextCursor')
inf --json inference list --sort input_tokens --order desc --cursor "$cursor"inf inference facets
Probe the active project for the values you can filter on — models, providers, environments, task IDs, and metadata keys — plus the full numeric/metadata/sort reference. Values are discovered from your data, not hardcoded, which makes this the starting point for building a filtered inf inference list query (and a one-call way for an AI agent to learn the filter surface).
Alias: inf inference filters
inf inference facetsAdd the global --json flag to emit a machine-readable object combining the probed values with a static reference (numeric fields, operators, and sort keys).
inf inference get
Fetch the complete stored request and response for a specific inference — method, path, headers, and the full request/response bodies (returned only when payload storage was enabled for the request; otherwise the sides come back null). Useful for debugging specific calls, inspecting model behavior, or archiving payloads.
inf inference get <id>Arguments
| Argument | Required | Description |
|---|---|---|
id | Yes | Full inference UUID or a 4+ character prefix |
Options
| Flag | Required | Description | Default |
|---|---|---|---|
--request | No | Output only the request (omit the response) | Both |
--response | No | Output only the response (omit the request) | Both |
--body | No | Output only the raw body content (no method/path/headers). Requires --request or --response | — |
-o, --output <path> | No | Write the output to a file instead of stdout | stdout |
Add the global --json flag to print the full { request, response } payload (method, path, headers, and complete bodies) as clean JSON for piping into jq or saving.
Examples
# Using a 4+ character UUID prefix (human-readable view)
inf inference get inf_abc1
# Pull a full UUID from list output, then fetch it
inf inference list --json | jq -r '.items[0].id' | xargs inf inference get
# Full request + response as clean JSON, then extract the response body
inf --json inference get <id> | jq '.response.body'
# Dump just the raw response body to a file
inf inference get <id> --response --body -o response.json