API reference · Usage
Spend over time, grouped, with a breakdown table
/v1/orgs/{org_id}/usage/costs- TypeScript
client.usage.getCostReport()- Python
client.usage.get_cost_report()- CLI
hayonix usage
Every amount is exactly what was charged to the organization's balance, dated by when the usage happened, so totals match the billing history to the nano-USD. Daily buckets cover at most 400 days and hourly buckets at most 31; an API key sees only its own project's spend.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the usage:read permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
# The org of your key: GET /v1/caller
ORG_ID=$(curl -sS "$API_BASE_URL/caller" -H "Authorization: Bearer $API_KEY" | jq -r .org_id)
curl -sS "$API_BASE_URL/orgs/$ORG_ID/usage/costs" \
-H "Authorization: Bearer $API_KEY"Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
Path parameters
org_idstringYour organization. The SDKs and the CLI fill it in from the API key.
ID with prefix org_
Query parameters
startstring (date-time)Inclusive; default the start of the current month (UTC)
endstring (date-time)Exclusive; default the start of next month
bucketstringDefault day (UTC)
One of
dayhourgroup_bystringDefault product
One of
productline_itemprojectapi_keyproject_idstringID of the project
ID with prefix prj_
Response
200 CostReport — The cost report
objectstringrequiredAlways `cost_report`: the type of this object
One of
cost_reportstartstring (date-time)requiredStart of the reported period (inclusive)
endstring (date-time)requiredEnd of the reported period (exclusive)
bucketstringrequiredWidth of each `series` bucket, aligned to UTC
One of
dayhourgroup_bystringrequiredWhat `key` identifies in `breakdown` and `series`: `product` (compute, inference, batch_inference, evaluations, training, storage, dedicated_endpoints, other), `line_item` (`<meter>:<price_key>`, the meter and price key of the price sheet), `project` (a project ID) or `api_key` (an API key ID, `none` for usage not made with a key)
One of
productline_itemprojectapi_keycurrencystringrequiredAlways `usd`
One of
usdtotalstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
breakdownarray of objectrequiredOne row per group, largest first
ShowHide 3 fields of
breakdownkeystringrequiredThe group, as chosen by `group_by`
totalstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
quantitystring | nullrequiredTotal units used in the period, as a decimal string, in the line item's meter unit (tokens, seconds, characters…); null unless `group_by` is `line_item`
seriesarray of objectrequiredSpend per bucket and group in time order; buckets and groups with no spend are left out
ShowHide 3 fields of
seriesbucket_startstring (date-time)requiredStart of the bucket (UTC)
keystringrequiredThe group, as chosen by `group_by`
amountstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
Example response
{
"object": "cost_report",
"start": "2026-01-01T00:00:00.000Z",
"end": "2026-01-01T00:00:00.000Z",
"bucket": "day",
"group_by": "product",
"currency": "usd",
"total": "1500000000",
"breakdown": [
{
"key": "string",
"total": "1500000000",
"quantity": "string"
}
],
"series": [
{
"bucket_start": "2026-01-01T00:00:00.000Z",
"key": "string",
"amount": "1500000000"
}
]
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |