Endpoints

GET /v1/usage

Summarizes spending and balance over the time range you request. By default, spend includes all workspaces in your organization, regardless of which workspace owns your API key.

Parameter	Values	Default	Description
`range`	`24h`, `7d`, `30d`, `period`	`30d`	Time window. `period` = the current billing period (a rolling 30 days today).
`workspace_id`	Workspace ID	All organization workspaces	Filters spend and token metrics, including `prior_period`, to one workspace.

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage?range=7d" | jq

{
  "object": "usage.summary",
  "range": "7d",
  "period_spend": 5432,
  "burn_rate": 776,
  "balance": 0,
  "balance_unavailable": true,
  "plan_type": "self_serve",
  "model_count": 3,
  "tokens": {
    "total": 1000000,
    "input": 600000,
    "output": 350000,
    "cached": 50000
  },
  "avg_cost_per_day": 776,
  "sla_mix": {
    "asap": 0.3,
    "standard": 0.7
  },
  "prior_period": {
    "period_spend": 4000,
    "model_count": 2,
    "tokens": {
      "total": 800000,
      "input": 500000,
      "output": 280000,
      "cached": 20000
    },
    "avg_cost_per_day": 571
  }
}

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, the response echoes it as a top-level field. plan_type still describes your organization, not a separate workspace plan. Workspace grouping is 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.

Parameter	Values	Default	Description
`range`	`24h`, `7d`, `30d`, `period`, `day`	`30d`	Time window.
`date`	`YYYY-MM-DD`	-	Required when `range=day`. Drills into hourly data for that date.
`workspace_id`	Workspace ID	All organization workspaces	Filters the entire response to one workspace.
`group_by`	`workspace`	Omitted	Adds a `workspaces` array with each workspace’s spend, tokens, time series, and model rankings.

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/breakdown?range=7d" | jq

{
  "object": "usage.breakdown",
  "range": "7d",
  "granularity": "day",
  "data": [
    {
      "timestamp": "2025-01-15",
      "total": 800,
      "models": {
        "zai-org/GLM-5.2": {
          "total": 500,
          "tokens": 50000,
          "input_tokens": 30000,
          "output_tokens": 15000,
          "cached_tokens": 5000
        }
      },
      "slas": { "standard": 800 }
    }
  ],
  "models": [
    {
      "model": "zai-org/GLM-5.2",
      "total": 3500,
      "tokens": 350000,
      "input_tokens": 210000,
      "output_tokens": 105000,
      "cached_tokens": 35000,
      "slas": { "standard": 3500 },
      "percentage": 0.65
    }
  ]
}

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:

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/breakdown?range=day&date=2026-09-07&workspace_id=ws_prod" \
  | jq '.models[] | {model, dollars: (.total / 100)}'

Use the same workspace_id parameter on /v1/usage for a filtered summary, including its prior-period comparison:

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage?range=7d&workspace_id=ws_prod" | jq

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:

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/breakdown?range=day&date=2026-09-07&group_by=workspace" \
  | jq '[.workspaces[] | {
      workspace_id,
      workspace_name,
      dollars: (.total / 100),
      models: [.models[] | {model, dollars: (.total / 100)}]
    }]'

For example, the command above can produce:

[
  {
    "workspace_id": "ws_prod",
    "workspace_name": "Production",
    "dollars": 125,
    "models": [
      { "model": "zai-org/GLM-5.3", "dollars": 100 },
      { "model": "claude-opus-5", "dollars": 25 }
    ]
  },
  {
    "workspace_id": "ws_dev",
    "workspace_name": "Development",
    "dollars": 10,
    "models": [
      { "model": "zai-org/GLM-5.3", "dollars": 10 }
    ]
  }
]

The API response keeps the existing top-level data and models fields and adds group_by: "workspace" and workspaces. Each workspace contains:

Field	Description
`workspace_id`	Stable workspace ID. Use this for filters and joins, even if the workspace is renamed.
`workspace_name`	Current workspace display name.
`total`	Total spend over the requested range, in cents.
`tokens`	Token counts: `total`, fresh `input`, `output`, and `cached`.
`data`	The same time-bucket structure as top-level `data`, limited to this workspace.
`models`	The same model-ranking structure as top-level `models`. Each `percentage` is relative to this workspace’s spend.

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.

GET /v1/usage/activity

Surfaces operational metrics - request counts, token throughput, latency, and a list of recent requests.

Parameter	Values	Default	Description
`limit`	`1`–`100`	`10`	Number of recent requests to return.

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  https://api.valarhq.ai/v1/usage/activity | jq

{
  "object": "usage.activity",
  "available": true,
  "requests": {
    "last_1m": 5,
    "last_1h": 120,
    "last_24h": 2000,
    "last_7d": 14000
  },
  "tokens": {
    "last_1m": 500,
    "last_1h": 12000,
    "last_24h": 200000,
    "last_7d": 1400000,
    "token_breakdown_1h": {
      "input": 8000,
      "output": 3500,
      "cached": 500
    }
  },
  "latency": {
    "avg_1m_ms": 1200,
    "avg_1h_ms": 1500
  },
  "recent_requests": [
    {
      "response_id": "resp_abc123",
      "model": "zai-org/GLM-5.2",
      "sla": "standard",
      "status": "completed",
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:01:00Z"
    }
  ],
  "has_more": false
}

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.

Parameter	Values	Default	Description
`type`	`requests`, `tokens`	`requests`	What to chart.
`range`	`1h`, `6h`, `24h`	`24h`	Time window. Bucket size: 1min / 5min / 1 hour respectively.

Requests by model:

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/activity/timeseries?type=requests&range=1h" | jq

{
  "object": "usage.activity.timeseries",
  "type": "requests",
  "range": "1h",
  "available": true,
  "series": [
    {
      "time_bucket": "2025-01-15T10:00:00Z",
      "model": "zai-org/GLM-5.2",
      "count": 5
    },
    {
      "time_bucket": "2025-01-15T10:01:00Z",
      "model": "zai-org/GLM-5.2",
      "count": 3
    }
  ]
}

Token breakdown:

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/activity/timeseries?type=tokens&range=24h" | jq

{
  "object": "usage.activity.timeseries",
  "type": "tokens",
  "range": "24h",
  "available": true,
  "series": [
    {
      "time_bucket": "2025-01-15T10:00:00Z",
      "total_tokens": 1000,
      "input_tokens": 600,
      "output_tokens": 350,
      "cached_tokens": 50
    }
  ]
}

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. All three share the same window and filter parameters.

Window

Pick one of the two forms. Combining them returns 400.

Parameter	Values	Default	Description
`range`	`1h`, `24h`, `7d`, `30d`, `period`, `mtd`	`30d`	Preset window ending now. `7d`, `30d`, and `period` are whole UTC days ending today; `mtd` is the current UTC calendar month to date; `1h` is the last rolling hour; `24h` is the last rolling 24 hours, not the current UTC day.
`start`, `end`	`YYYY-MM-DD`	-	An explicit window of whole UTC days, both bounds inclusive. Both are required together; `start` must not be after `end`, `end` must not be after today, and the span is at most 366 days. The response echoes `"range": "custom"`.

Filters

Every filter narrows the rows before they are aggregated, so the filters compose with each other and with any window.

Parameter	Description
`key_id`	One coding key. Use the `id` from the key list or the dashboard.
`cohort_id`	One routing cohort.
`model`	One served model id, as it appears in `served_model`.
`byok`	`true` restricts the view to traffic served on your own upstream credentials. Omitted, the view excludes BYOK traffic.

GET /v1/usage/coding/keys

One row per coding key, ranked by spend.

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/coding/keys?start=2026-08-01&end=2026-08-31" | jq

{
  "object": "usage.coding.keys",
  "range": "custom",
  "keys": [
    {
      "key_id": "key_01J9X4M2K7Q3",
      "key_name": "[email protected]",
      "requests": 1840,
      "engineers": 1,
      "tokens": 60850000,
      "input_tokens": 59700000,
      "output_tokens": 1150000,
      "cached_tokens": 55600000,
      "cache_write_tokens": 400000,
      "successes": 1831,
      "failures": 9,
      "spend": 18420,
      "baseline_spend": 61300,
      "savings": 42880,
      "savings_pct": 0.6995
    }
  ]
}

Field	Description
`key_id`, `key_name`	The key’s stable id and its current display name. For an automation-provisioned key the name is the engineer’s email.
`requests`	Requests the coding lane routed for this key in the window.
`engineers`	Distinct engineer ids seen on the key.
`tokens`	`input_tokens + output_tokens`.
`input_tokens`	All input tokens, including the cached ones. `input_tokens - cached_tokens` is the fresh input.
`output_tokens`	Generated tokens.
`cached_tokens`	The part of `input_tokens` served from the prompt cache.
`cache_write_tokens`	Input tokens written to the prompt cache. Counted separately from `input_tokens` and priced at the cache-write rate.
`successes`, `failures`	Requests that completed vs. failed.
`spend`	What Valar billed for the key’s traffic, in cents.
`baseline_spend`, `savings`, `savings_pct`	What the same traffic would have cost at Anthropic list prices, the difference, and the difference as a fraction of the baseline.

GET /v1/usage/coding/models

One row per served model, ranked by spend. Add key_id to get one key’s model mix.

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/coding/models?start=2026-08-01&end=2026-08-31&key_id=key_01J9X4M2K7Q3" | jq

{
  "object": "usage.coding.models",
  "range": "custom",
  "models": [
    {
      "served_model": "zai-org/GLM-5.2",
      "requests": 1420,
      "tokens": 47800000,
      "input_tokens": 46900000,
      "output_tokens": 900000,
      "cached_tokens": 43900000,
      "cache_write_tokens": 300000,
      "spend": 9210,
      "share": 0.5
    },
    {
      "served_model": "claude-opus-5",
      "requests": 420,
      "tokens": 13050000,
      "input_tokens": 12800000,
      "output_tokens": 250000,
      "cached_tokens": 11700000,
      "cache_write_tokens": 100000,
      "spend": 9210,
      "share": 0.5
    }
  ]
}

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.

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.

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/coding/requests?engineer_id=amara&limit=5" | jq

{
  "object": "usage.coding.requests",
  "engineer_id": "amara",
  "data": [
    {
      "response_id": "resp_01J9X4M2K7Q3",
      "created_at": "2026-09-15T10:04:00Z",
      "harness": "claude",
      "class": "medium",
      "served_model": "zai-org/GLM-5.3-fast",
      "status": "completed"
    },
    {
      "response_id": "resp_01J9X4M2K7Q4",
      "created_at": "2026-09-15T10:03:00Z",
      "harness": "claude",
      "class": "high",
      "served_model": "claude-opus-5",
      "status": "failed",
      "failure_code": "rate_limit"
    }
  ]
}

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. The tiers correspond to the Claude families: low to Haiku, medium to Sonnet, high to Opus and max to Fable. The feed reports the tier rather than the family because a request need not arrive as a Claude alias at all: an explicit pick of an open-weight model resolves to a tier too. The feed 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 for a quota shed. A request the upstream rejected shows failed with no failure_code. 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/timeseries

A bucketed request series for charts. This endpoint takes a window (6h, 24h, 7d, 30d, default 24h) instead of range or start/end, because its buckets are aligned to the current clock and the final bucket is still filling. It accepts the same filters, so ?window=7d&key_id=… charts one key.

Putting it together

Per-key cost and token usage for a calendar month, then the model mix behind the top key:

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/coding/keys?start=2026-08-01&end=2026-08-31" \
  | jq '.keys[] | {key_name, dollars: (.spend / 100), input_tokens, output_tokens}'

TOP_KEY=$(curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/coding/keys?start=2026-08-01&end=2026-08-31" \
  | jq -r '.keys[0].key_id')

curl -s -H "Authorization: Bearer $VALAR_API_KEY" \
  "https://api.valarhq.ai/v1/usage/coding/models?start=2026-08-01&end=2026-08-31&key_id=$TOP_KEY" \
  | jq '.models[] | {served_model, dollars: (.spend / 100), share}'

Spend is integer cents, like the rest of the Usage API. The rollup behind these endpoints is per UTC day and lags live traffic by a few minutes; range=1h reads the live ledger instead and is the only sub-day view.

Errors

Errors share the format used throughout the inference API:

{
  "error": {
    "message": "Missing or invalid Authorization header",
    "type": "authentication_error",
    "param": null,
    "code": null
  }
}

HTTP Status	`type`	When
400	`invalid_request_error`	Bad query parameter, or a missing required one
401	`authentication_error`	Missing, invalid, or expired API key
404	`invalid_request_error`	Unknown route or unsupported method
500	`api_error`	Internal server error

Response headers

Each response carries an X-Request-ID: <uuid>. Quote it in support requests to speed up troubleshooting.

Responses

Chat completions

Files

Batches

Models

Usage

Models API

Responses API

Chat Completions API

Batches API

Files API

GET /v1/usage

GET /v1/usage/breakdown

Workspace filtering and breakdowns

GET /v1/usage/activity

GET /v1/usage/activity/timeseries

ValarCode analytics

Window

Filters

GET /v1/usage/coding/keys

GET /v1/usage/coding/models

GET /v1/usage/coding/requests

GET /v1/usage/coding/timeseries

Putting it together

Errors

Response headers

​GET /v1/usage

​GET /v1/usage/breakdown

​Workspace filtering and breakdowns

​GET /v1/usage/activity

​GET /v1/usage/activity/timeseries

​ValarCode analytics

​Window

​Filters

​GET /v1/usage/coding/keys

​GET /v1/usage/coding/models

​GET /v1/usage/coding/requests

​GET /v1/usage/coding/timeseries

​Putting it together

​Errors

​Response headers

GET /v1/usage

GET /v1/usage/breakdown

Workspace filtering and breakdowns

GET /v1/usage/activity

GET /v1/usage/activity/timeseries

ValarCode analytics

Window

Filters

GET /v1/usage/coding/keys

GET /v1/usage/coding/models

GET /v1/usage/coding/requests

GET /v1/usage/coding/timeseries

Putting it together

Errors

Response headers