Skip to main content
Need your Valar usage figures inside a script, CLI tool, or custom dashboard? The Usage API exposes them directly. It authenticates with the very same key that powers your calls to api.valarhq.ai.

Base URL

Authentication

Pass your API key as a Bearer token in the Authorization header on every request.
The key here is identical to the one used by the inference API at api.valarhq.ai. Generate and manage keys from the Valar dashboard.

Endpoints

The complete reference for each GET /v1/usage route, covering parameters, response shapes, error formats, and headers.

Organization, workspace, and API key costs

By default, /v1/usage and /v1/usage/breakdown include all workspaces and API keys in your organization, not just the workspace or key you authenticate with.
  • Add workspace_id=ws_... to either endpoint to filter costs to one workspace.
  • Add key_id=... to either endpoint to filter costs to one API key.
  • Add group_by=workspace or group_by=key to /v1/usage/breakdown to get IDs, names, totals, and per-model costs for each workspace or each API key in one response.
To compare with the dashboard’s This workspace view, filter the API request to the same workspace and UTC date range. For an unfiltered API request, compare with All workspaces instead. All API monetary values are integer cents; divide by 100 to get dollars. See workspace filtering and breakdowns and API key filtering and breakdowns for examples and response fields. These options apply to the two spend endpoints, not the activity or coding endpoints.
Expect a small lag in usage data - it is not reported in real time.
Need the figure per request, as it happens? Per-request cost reporting puts the price of each response in its usage.cost.