Skip to content
Hayonix

API reference · Billing

Get the credit balance

GET/v1/orgs/{org_id}/billing/balance
API keybilling:readOrganization
TypeScript
client.billing.getBalance()
Python
client.billing.get_balance()
CLI
hayonix balance

Returns paid and promotional credit, the amount reserved by work in progress, and what is available for new work. Recent inference spending can take up to about 30 seconds to appear.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the billing: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/billing/balance" \
  -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_

Response

200 Balance — The current balance

  • objectstringrequired

    Always `balance`: the type of this object

    One ofbalance

  • org_idstringrequired

    Organization it belongs to

    ID with prefix org_

  • currencystringrequired

    Always `usd`

    One ofusd

  • paidstringrequired

    Paid credit; negative when overdrawn

    pattern ^-?[0-9]+$

  • promostringrequired

    Spendable promotional credit

    pattern ^-?[0-9]+$

  • heldstringrequired

    Reserved by in-flight work

    pattern ^-?[0-9]+$

  • availablestringrequired

    paid + promo: what new work may use

    pattern ^-?[0-9]+$

  • as_ofstring (date-time)required

    When these amounts were read (ISO 8601, UTC)

Example response
Example response
{
  "object": "balance",
  "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "currency": "usd",
  "paid": "1500000000",
  "promo": "1500000000",
  "held": "1500000000",
  "available": "1500000000",
  "as_of": "2026-01-01T00:00:00.000Z"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
402insufficient_credit_errorThe organization is out of credit or over a spend limit.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.