API reference · Billing
The rate-limit level: per-minute limits in force and what reaches the next level
/v1/orgs/{org_id}/billing/rate-level- TypeScript
client.billing.getRateLevel()- Python
client.billing.get_rate_level()- CLI
hayonix billing rate-limits
Inference and batch requests and tokens per minute (per model) come from the organization’s level. A level is reached by credit paid and kept and by account age, both at once; it rises by itself (right after a payment, and as the account ages) and never goes down by itself. A limit set for this organization by the platform wins over its level.
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/rate-level" \
-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_
Response
200 RateLevel — The rate-limit level
objectstringrequiredAlways `rate_level`: the type of this object
One of
rate_levelorg_idstringrequiredOrganization it belongs to
ID with prefix org_
The level in force
ShowHide 2 fields of
levelidstringrequiredLevel identifier
labelstringrequiredName to show
earnedany JSONrequiredShowHide 2 fields of
earnedidstringrequiredLevel identifier
labelstringrequiredName to show
set_by_platformbooleanrequiredThe platform set this organization’s level; it does not move by itself until that is lifted
limitsobjectrequiredPer-minute limits in force, per model
ShowHide 4 fields of
limitsShowHide 2 fields of
inference_rpmlimitintegerrequiredThe limit that applies now
sourcestringrequired`level`: from the organization’s level. `override`: set for this organization by the platform; it wins over the level.
One of
leveloverride
ShowHide 2 fields of
inference_tpmlimitintegerrequiredThe limit that applies now
sourcestringrequired`level`: from the organization’s level. `override`: set for this organization by the platform; it wins over the level.
One of
leveloverride
ShowHide 2 fields of
batch_rpmlimitintegerrequiredThe limit that applies now
sourcestringrequired`level`: from the organization’s level. `override`: set for this organization by the platform; it wins over the level.
One of
leveloverride
ShowHide 2 fields of
batch_tpmlimitintegerrequiredThe limit that applies now
sourcestringrequired`level`: from the organization’s level. `override`: set for this organization by the platform; it wins over the level.
One of
leveloverride
Where the organization stands: credit paid and kept (refunds and open disputes deducted; promotional credit does not count) and account age
ShowHide 2 fields of
progresspaid_creditstringrequiredCredit paid by card and kept (nano-USD)
pattern ^-?[0-9]+$
account_age_daysintegerrequiredDays since the organization was created
nextobject | nullrequiredThe next level and what reaching it takes; null on the highest level
ShowHide 3 fields of
nextThe level in force
ShowHide 2 fields of
levelidstringrequiredLevel identifier
labelstringrequiredName to show
Where the organization stands: credit paid and kept (refunds and open disputes deducted; promotional credit does not count) and account age
ShowHide 2 fields of
requirespaid_creditstringrequiredCredit paid by card and kept (nano-USD)
pattern ^-?[0-9]+$
account_age_daysintegerrequiredDays since the organization was created
missingany JSONrequiredShowHide 2 fields of
missingpaid_creditstringrequiredCredit paid by card and kept (nano-USD)
pattern ^-?[0-9]+$
account_age_daysintegerrequiredDays since the organization was created
levelsarray of objectrequiredEvery level, lowest first
ShowHide 3 fields of
levelsThe level in force
ShowHide 2 fields of
levelidstringrequiredLevel identifier
labelstringrequiredName to show
Where the organization stands: credit paid and kept (refunds and open disputes deducted; promotional credit does not count) and account age
ShowHide 2 fields of
requirespaid_creditstringrequiredCredit paid by card and kept (nano-USD)
pattern ^-?[0-9]+$
account_age_daysintegerrequiredDays since the organization was created
ShowHide 4 fields of
limitsinference_rpmintegerrequiredInference requests per minute, per model
inference_tpmintegerrequiredInference tokens (prompt + completion) per minute, per model
batch_rpmintegerrequiredBatch requests per minute, per model
batch_tpmintegerrequiredBatch tokens per minute, per model
Example response
{
"object": "rate_level",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"level": {
"id": "level_2",
"label": "Level 2"
},
"earned": {
"id": "level_2",
"label": "Level 2"
},
"set_by_platform": true,
"limits": {
"inference_rpm": {
"limit": 1,
"source": "level"
},
"inference_tpm": {
"limit": 1,
"source": "level"
},
"batch_rpm": {
"limit": 1,
"source": "level"
},
"batch_tpm": {
"limit": 1,
"source": "level"
}
},
"progress": {
"paid_credit": "1500000000",
"account_age_days": 1
},
"next": {
"level": {
"id": "level_2",
"label": "Level 2"
},
"requires": {
"paid_credit": "1500000000",
"account_age_days": 1
},
"missing": {
"paid_credit": "1500000000",
"account_age_days": 1
}
},
"levels": [
{
"level": {
"id": "level_2",
"label": "Level 2"
},
"requires": {
"paid_credit": "1500000000",
"account_age_days": 1
},
"limits": {
"inference_rpm": 1,
"inference_tpm": 1,
"batch_rpm": 1,
"batch_tpm": 1
}
}
]
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
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. |
402 | insufficient_credit_error | The organization is out of credit or over a spend limit. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |