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 and workspace costs

By default, /v1/usage and /v1/usage/breakdown include all workspaces in your organization, not just the workspace that owns your API key.
  • Add workspace_id=ws_... to either endpoint to filter costs to one workspace.
  • Add group_by=workspace to /v1/usage/breakdown to get workspace IDs, names, totals, and per-model costs 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 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.