GET /v1/usage
Summarizes spending and balance over the time range you request. By default, spend includes all workspaces and API keys in your organization, regardless of which workspace owns your API key.Every monetary value is expressed in cents. The
prior_period block
mirrors the same-length window directly preceding your requested range, so you
can compare the two.workspace_id or key_id, the response echoes it as a top-level
field. plan_type still describes your organization, not a separate workspace plan.
Workspace and API key grouping are available on /v1/usage/breakdown, not this endpoint.
The keys in
sla_mix are completion window names:
asap (the Now tier), standard, and flex.balance, balance_unavailable, and days_remaining describe a prepaid-credit balance.
Until prepaid credits are available, balance_unavailable is always true, balance is
0, and days_remaining is omitted - spend, burn rate, tokens, and the SLA mix are always
reported.GET /v1/usage/breakdown
Provides per-model rankings alongside time-series spend data - ideal for building charts.granularity is "day"; for a 24h range or a day drill-down it is "hour".
Workspace filtering and breakdowns
To retrieve one workspace’s costs for a UTC day:workspace_id parameter on /v1/usage for a filtered summary,
including its prior-period comparison:
group_by=workspace.
This also gives you the workspace IDs to use in filtered requests:
data and models fields and adds
group_by: "workspace" and workspaces. Each workspace contains:
Workspaces are sorted by
total descending, then by workspace_id. Only workspaces
with usage records in the selected range are included; a workspace with tokens
but zero spend is still included. An empty result returns workspaces: [].
BYOK usage remains excluded, as it is from the ungrouped spend response.
You can combine workspace_id and group_by=workspace. The top-level totals and
the workspace array then include only that workspace. The response echoes the
filter in a top-level workspace_id field. Without either parameter, the response
shape and organization-wide scope stay unchanged.
A workspace filter can only narrow your authenticated organization’s usage.
An unknown workspace ID, a workspace outside your organization, or a workspace
without usage returns an empty breakdown and zero summary usage metrics.
An omitted or empty
workspace_id includes all of your organization’s workspaces.All monetary fields in the API response are integer cents. The
dollars fields
above are calculated by jq, not returned by the API. Values are rounded after
aggregation, so summing separately rounded workspace or bucket totals can differ
slightly from a combined total. Match the dashboard’s workspace scope and UTC
date range when comparing costs; usage data can also lag slightly.API key filtering and breakdowns
To see what each API key spent, usegroup_by=key. The response covers every API
key in your organization with usage in the range, including ValarCode keys. Each
key’s row uses the same fields as /v1/usage/coding/keys:
data and models fields and adds
group_by: "key" and keys. Each key contains:
In
keys, as in /v1/usage/coding/keys, input_tokens includes cached tokens.
In the model rankings (models) of this endpoint, input_tokens is fresh input
only, and tokens is fresh input + cached + output.spend descending, then by key_id. Only keys with usage
records in the selected range are included; a key with tokens but zero spend is
still included. Usage that is not attributed to an API key appears under an empty
key_id. An empty result returns keys: []. BYOK usage remains excluded, as it is
from the ungrouped spend response.
To retrieve one key’s costs, pass its key_id to /v1/usage or /v1/usage/breakdown:
key_id field. You can combine
key_id with workspace_id, and either filter with one group_by value. For
example, workspace_id=ws_prod&group_by=key lists the keys in one workspace.
Each request groups by one dimension: workspace or key.
A key filter can only narrow your authenticated organization’s usage. An unknown
key ID, a key outside your organization, or a key without usage returns an empty
breakdown and zero summary usage metrics. An omitted or empty
key_id includes all
of your organization’s API keys.GET /v1/usage/activity
Surfaces operational metrics - request counts, token throughput, latency, and a list of recent requests.has_more value of true means more recent requests exist beyond the limit you asked for.
Like the other endpoints, activity data lags slightly and is not delivered as
a real-time stream.
GET /v1/usage/activity/timeseries
Returns bucketed series for either requests or tokens - use it to draw throughput charts.
Requests by model:
ValarCode analytics
The/v1/usage/coding/* endpoints report the traffic your ValarCode keys
send through the coding lane: which key, which engineer, which model was served, and what it cost.
They accept the same Authorization: Bearer API key as the endpoints above (a coding key or a
standard key) and always cover the whole organization. Unlike the endpoints above, they also
accept the organization automation credential as the bearer, so
a provisioning service that manages keys can read their usage with the token it already holds.
An engineer’s own SSO sign-in can call these endpoints too, as valar usage does.
It reads only that engineer’s usage, whatever filters it sends. It can read
/v1/usage/coding/models, /v1/usage/coding/savings, /v1/usage/coding/requests and
/v1/usage/coding/sessions. Every other endpoint answers 403.
They share the window and filter parameters below, except /v1/usage/coding/requests and
/v1/usage/coding/sessions, which take only engineer_id and limit and cover the last 7 days.
Window
Pick one of the two forms. Combining them returns400.
Filters
Every filter narrows the rows before they are aggregated, so the filters compose with each other and with any window.
To read one engineer’s usage, pass
engineer_id. This is the simplest way to read an SSO sign-in’s
usage: use the work email shown in its key_name. Matching is exact, so pass the id exactly as
usage shows it. Usage from ids you merged into the engineer under Identity on
ValarCode → Users is included. A coding key provisioned for one engineer always reads its own
usage and ignores engineer_id.
GET /v1/usage/coding/keys
One row per coding key, ranked by spend. With SSO sign-in on, each engineer who made requests with a sign-in in the window also has a row of their own.GET /v1/usage/coding/models
One row per served model, ranked by spend. Addkey_id to get one key’s model mix.
served_model is the model that actually answered, which under Auto routing can differ from the
model the coding tool asked for. share is the model’s fraction of the spend in the response
(0–1), so with a key_id filter it is the share of that key’s spend.
Add split=strategy to get one row per model and Auto-Router strategy instead. Each row then has a
strategy field (balanced, max_savings, max_quality, us_only or custom) naming the
strategy that picked the model. The field is absent on the row for traffic the router did not pick.
The by-model savings view (/v1/usage/coding/savings) takes the same parameter.
With byok=true, spend is 0 on every row, because Valar charges nothing for traffic on your own
credentials. Each row then also has list_price_spend: the row’s tokens at the model’s list
prices, in cents. It estimates what your provider charged and does not include discounts or
commitments you have with them, or a model’s higher rate for very long prompts.
GET /v1/usage/coding/requests
The last requests one engineer made, newest first. This is the per-request view: everything else on this page is an aggregate, so this is where you attribute a single turn to the model that answered it.engineer_id is required. limit defaults to 10 and accepts 1-100. The feed covers the last
7 days and spans every coding harness, so a Claude Code turn, a Cursor completion and a Codex run
all appear in one list, each tagged by its harness.
class is the routing tier the request resolved into, one of low, medium, high or max, and
served_model is what answered. Under Auto routing they differ by design.
strategy is the Auto-Router strategy that picked served_model: balanced, max_savings,
max_quality, us_only or custom. It is absent when the router did not pick the model, for
example when the tool named a model itself or your routing maps that tier to a fixed model.
surface is where the harness ran, as its client reports it: cli for Claude Code in a terminal,
claude-desktop or claude-desktop-3p for Claude Code inside the Claude desktop app, codex-tui or
codex_exec for Codex. harness names the tool either way, so a turn from the desktop app’s Code tab
reads "harness": "claude" with a desktop surface. It is absent when the client does not say, and
on requests recorded before the field was added.
The feed reports the tier a request resolved into, from low to max, rather than the model the
tool asked for. It does not carry the exact model id the tool sent.
status is the request’s terminal state (completed, incomplete, failed, cancelled) and
failure_code is present only when Valar itself refused the request, for example rate_limit when
your request rate or spend limit refused it, or capacity_limit when Valar was at capacity. Both
reach the client as a 429 rate limit to retry with backoff; only rate_limit is your own limit. A
request that failed during generation shows failed with no failure_code.
byok is true when the request ran on your organization’s own provider key (BYOK). Valar bills
nothing for those requests, so their spend_micro_usd is 0 whatever the model. valar usage shows
them as BYOK:<model>.
response_id is Valar’s own id for the request. It is not the id your client sees on the
response, so use it the way this feed hands it to you: find the row by time, then quote its
response_id to support.
valar usage prints this feed at the bottom of its output, so an engineer can read it without
writing a request. Use -n to ask for more rows.GET /v1/usage/coding/sessions
One engineer’s most recently active sessions, newest first, each with its totals and the models that served it. A session is the tool’s own session: for Claude Code, the idclaude --resume takes.
Only tools that send a session id appear, such as Claude Code, Codex and Pi; harness names the
tool. Cursor sends none, so its traffic is not listed.
engineer_id is required. limit defaults to 10 and accepts 1-100. The list covers sessions
active in the last 7 days.
/v1/usage/coding/requests: input_tokens includes
cached_tokens, and cache_write_tokens is counted apart. spend_micro_usd is in millionths of a
dollar. models lists every model that served the session, most expensive first.
byok_requests is how many of requests ran on your organization’s own provider key (BYOK). Valar
bills nothing for those, so spend_micro_usd covers the other requests only, while the token fields
count all of them. One session can mix both on the same model.
GET /v1/usage/coding/timeseries
A bucketed request series for charts. It takes the samerange or start/end window as the
other coding endpoints, up to 31 days, and picks the bucket size from the window’s length: one
minute for the last hour, up to four hours for a month. The response echoes the window as range,
start and end. A window that ends now has a final bucket that is still filling, marked
"partial": true. It accepts the same filters except engineer_id, so ?range=7d&key_id=… charts
one key.
The older window parameter (6h, 24h, 7d, 30d, default 24h) still works when no range
or start/end is given: a rolling window aligned to the current clock.
Putting it together
Per-key cost and token usage for a calendar month, then the model mix behind the top key:Spend is integer cents, like the rest of the Usage API. Daily figures are per UTC day and
lag live traffic by a few minutes;
range=1h is near-live and the only sub-day view.Errors
Errors share the format used throughout the inference API:Response headers
Each response carries anX-Request-ID: <uuid>. Quote it in support requests to speed up troubleshooting.