deeprelayDocs
CH·02CLI reference

deeprelay requests list

List requests, newest first

List requests, newest first

Synopsis

Lists requests from the request log, newest first. With no filters it returns the most recent page of everything you can see (see deeprelay requests for the visibility rule).

Filters (combine freely; each narrows the result):

  • --key — requests made with one API key (the key id from deeprelay api-keys list, not the key itself)
  • --model — one model id, e.g. deeprelay/deepseek-v4.1-flash
  • --surface — chat, messages, responses, embeddings, image or video
  • --status — ok, error, cancelled or rejected (refused at admission, not charged)
  • --error-code — requests that ended with one error code, e.g. api_key_budget_exceeded
  • --client-request-id — requests you tagged with the X-Client-Request-Id header
  • --from / --to — a time range, as RFC3339 (2026-10-01T09:00:00Z) or a date (2026-10-01, midnight UTC). A start older than 90 days is clamped to the window.
  • --fallback — only requests that moved past the requested model to a backup (see deeprelay api-keys create), whether a backup served or the whole chain failed

An invalid --surface, --status, time or --limit is refused before any request is sent.

Output. The table shows TIME SURFACE MODEL KEY STATUS FB TOKENS COST DURATION. MODEL is the model that answered. FB shows ↩ on a request that fell back to a backup model and is blank otherwise; deeprelay requests get shows the requested model, the reason and every model tried. Status reads Success, Failed, Rejected or Cancelled, with the error code beside Failed and Rejected. Tokens read in / out; a cell that does not apply to a row (output tokens for embeddings, tokens for images and video, anything for a rejected request) is left empty rather than shown as 0. Cost is the exact amount charged, the same figure as usage.cost on the response. With -o json the CLI prints the API page as-is: data, next_cursor and window_days. Each row carries requested_model, plus served_model, fallback_reason and attempts when they apply.

Paging. Pages hold 50 rows by default, up to 100 with --limit. When more rows remain, the CLI prints Next cursor: to stderr (never stdout, so -o json stays parseable); pass it back with --cursor and the same filters.

Exit status is 0 on success and 1 on any error.

Examples

# Everything that was refused at admission this month
deeprelay requests list --status rejected --from 2026-10-01

# Failures on one model, as JSON for a script
deeprelay requests list --model deeprelay/deepseek-v4.1-flash --status error -o json

# Requests that fell back to a backup model today
deeprelay requests list --fallback --from 2026-10-21

# Next page
deeprelay requests list --status rejected --from 2026-10-01 --cursor "$NEXT_CURSOR"

deeprelay requests list [flags]

Options

      --client-request-id string   Only requests carrying this client request id
      --cursor string              Pagination cursor from a previous list (see the stderr hint)
      --error-code string          Only requests that ended with this error code
      --fallback                   Only requests a backup model served or that tried backups
      --from string                Start of the time range (RFC3339 or YYYY-MM-DD, UTC); clamped to the 90-day window
  -h, --help                       help for list
      --key string                 Only requests made with this API key id
      --limit int                  Rows per page, 1-100 (server default 50)
      --model string               Only requests for this model id
      --status string              Only this status: ok | error | cancelled | rejected
      --surface string             Only this surface: chat | messages | responses | embeddings | image | video
      --to string                  End of the time range (RFC3339 or YYYY-MM-DD, UTC)

Options inherited from parent commands

      --api-base string   API base URL (override with DEEPRELAY_API_BASE env) (default "https://api.deeprelay.ai/v1")
      --debug             Enable debug logging to stderr
      --no-preflight      Skip the plan/credit check before inference requests (override with DEEPRELAY_NO_PREFLIGHT env)
  -o, --output string     Output format: table|json (default table on TTY, json otherwise) (default "table")

SEE ALSO

← The deeprelay CLI