/v1): a usage summary for
cost and tokens over time, the request log for individual calls, and how to attribute spend to a
single end user. The dashboard renders the same data — this is the API
behind it.
These reads require the
logs.read capability. Authenticate with your dashboard session or a
management key (rd_mk_…) — see Automate with a management
key. The examples below use a management key.Prerequisites
1. A usage summary: cost and tokens over time
The summary aggregates durable usage rollups (never a raw log scan), grouped by any subset ofday, model, and env. Ask for daily totals by model over a window:
requests, errors, tokens_in, tokens_out, and cost_usd. group_by accepts
a comma-separated subset of day, model, env; granularity is hour or day; add env to
scope to one environment. Omit from/to for the last 30 days.
cost_usd is the estimated provider cost, useful for analytics and budgets. It is not your
Roadie bill — Roadie meters on requests, not tokens (see
Billing & plans).2. The request log: individual calls
List recent requests with cursor pagination and rich filters. Each entry is metadata only (the payload lives on the detail route):env, status, model, end_user, error_code, and from/to. Page forward by
passing next_cursor as cursor. Notice model_requested: "smart" vs model_served: "anthropic/…" with retry_count: 2 — that is a fallback in
the logs.
3. One request in detail
Fetch a single request by id for the routing/metadata fields and — if your privacy mode retains it — the prompt/response payload, plus any end-user feedback:trace_id, metadata, fallback_chain, a feedback rollup, and the
privacy-gated payload. The payload is already privacy-mode-applied at write time — verbatim under
full, PII-stripped under redacted, and absent under metadata/none — so what you read is
exactly what the mode permits. (Image bytes are never stored; only the prompt and an
[omitted:image] marker are kept.)
4. Attribute usage and cost to one end user
Because every call is attributed to an end user, you can answer “why is this user’s bill high?”. Filter the log byend_user to see exactly what they ran:
user: { id } on server calls, or the id carried in a
client token).
5. Tie a live response back to its log
Every data-plane response carries anX-Request-Id header, and the SDK surfaces it as
res.requestId. That id is the log’s request_id — so from any response you can jump straight to
its detail:
res.requestId in your own error reporting and support tickets; it is the through-line from
a user complaint to the exact request.
6. Watch what you store: privacy modes
What the detail route can return is governed entirely by the environment’s privacy mode:development captures full by default; production defaults to metadata (no payload). A single
request may only tighten the mode via metadata: { privacy: 'metadata' }. Per-environment
log_retention_days (default 30) ages old logs out automatically. Usage records — tokens, cost,
status — are always kept regardless of mode, so metering and these summaries never go dark. See
Privacy modes.
What you built
You can now read Roadie’s operational data end to end: cost and token trends by day and model from the usage summary, individual requests (including fallbacks and errors) from the log, the full payload for a single request within your privacy mode, and spend attributed to any one end user. And from any live response’srequestId you can jump straight to its log entry — the link from a
user-facing symptom to the exact request.
Next steps
Per-user limits
Turn what you see into rate limits, quotas, and budgets.
Privacy modes
Decide how much of each request you retain.
Observability guide
The task-oriented reference for logs and usage.
Automate with a management key
Script these reads into a nightly report.