Skip to main content

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.
When you supply 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.
For 7d, 30d, and period ranges 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:
Use the same workspace_id parameter on /v1/usage for a filtered summary, including its prior-period comparison:
To separate costs by workspace in a single response, use group_by=workspace. This also gives you the workspace IDs to use in filtered requests:
For example, the command above can produce:
The API response keeps the existing top-level 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, use group_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:
For example, the command above can produce:
The API response keeps the existing top-level 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.
Keys are sorted by 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:
The response echoes the filter in a top-level 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.
For ValarCode keys, /v1/usage/coding/keys also reports engineers, cache_write_tokens, and the savings comparison. Its request counts include cancelled requests as failures, so they can be higher than requests here for the same key.

GET /v1/usage/activity

Surfaces operational metrics - request counts, token throughput, latency, and a list of recent requests.
A 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:
Token breakdown:

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 returns 400.

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. Add key_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.
class is the tier a request resolved into, not the one it asked for. Under Auto routing the router can re-class a request, so a Sonnet call sent to a low-tier model is recorded as low. Read the field as the routing decision.
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 id claude --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.
The token fields mean what they mean on /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 same range 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:
One engineer’s model mix for the same month, such as an engineer who uses an SSO sign-in:
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 an X-Request-ID: <uuid>. Quote it in support requests to speed up troubleshooting.