Skip to content
Hayonix

API reference · Usage

Spend over time, grouped, with a breakdown table

GET/v1/orgs/{org_id}/usage/costs
API keyusage:readOrganization
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

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.

Path parameters

  • org_idstring

    Your 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

  • bucketstring

    Default day (UTC)

    One ofdayhour

  • group_bystring

    Default product

    One ofproductline_itemprojectapi_key

  • project_idstring

    ID of the project

    ID with prefix prj_

Response

200 CostReport — The cost report

  • objectstringrequired

    Always `cost_report`: the type of this object

    One ofcost_report

  • startstring (date-time)required

    Start of the reported period (inclusive)

  • endstring (date-time)required

    End of the reported period (exclusive)

  • bucketstringrequired

    Width of each `series` bucket, aligned to UTC

    One ofdayhour

  • group_bystringrequired

    What `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 ofproductline_itemprojectapi_key

  • currencystringrequired

    Always `usd`

    One ofusd

  • totalstringrequired

    Integer nano-USD as a decimal string

    pattern ^-?[0-9]+$

  • breakdownarray of objectrequired

    One row per group, largest first

    Show 3 fields of breakdown
    • keystringrequired

      The group, as chosen by `group_by`

    • totalstringrequired

      Integer nano-USD as a decimal string

      pattern ^-?[0-9]+$

    • quantitystring | nullrequired

      Total 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 objectrequired

    Spend per bucket and group in time order; buckets and groups with no spend are left out

    Show 3 fields of series
    • bucket_startstring (date-time)required

      Start of the bucket (UTC)

    • keystringrequired

      The group, as chosen by `group_by`

    • amountstringrequired

      Integer nano-USD as a decimal string

      pattern ^-?[0-9]+$

Example response
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:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.