Balance and usage

Two endpoints give your account’s balance and usage. Use the same API key that you use for chat requests.

Setting	Value
Base URL	`https://api.paretoinference.com/v1`
Authentication	`Authorization: Bearer <API_KEY>`
Rate limit	20 requests each minute for each key and endpoint, with a burst of 5

These requests do not use your chat rate limits. They do not cost credits.

Get the balance

GET /balance

curl https://api.paretoinference.com/v1/balance \
  -H "Authorization: Bearer $PARETO_API_KEY"

{
  "object": "balance",
  "scope": "account",
  "currency": "USD",
  "account": {"type": "user", "id": "...a1b2"},
  "key": {"name": null, "suffix": "sk-...c3d4", "spend_today": null, "spend_month": null},
  "balance": "12.500000",
  "paid": "10.000000",
  "promo": "2.500000",
  "allowance_remaining": null,
  "held": "0.000000",
  "debt": "0.000000",
  "spend_today": "0.412000",
  "spend_month": "3.980000",
  "as_of": "2026-09-27T20:47:38Z",
  "spend_as_of": "2026-09-27T20:47:30Z"
}

Field	Meaning
`balance`	The credits you can spend. `held` and `debt` are already taken out, so it is negative while debt is larger than your credits. This is the same value as the dashboard.
`paid`	The part of `balance` from purchased credits. Debt is repaid from purchased credits only, so `paid` is negative while debt is larger than them.
`promo`	The part of `balance` from bonus credits. `paid` plus `promo` equals `balance`.
`allowance_remaining`	The allowance left in the current plan period. It is not part of `balance`. It is `null` when the account has no plan.
`held`	Credits reserved for requests in progress. They are already taken out of `balance`.
`debt`	Charges that your credits did not cover. It is already taken out of `balance`.
`spend_today`	Your charges for the current UTC day.
`spend_month`	Your charges for the current UTC month.
`as_of`	When the API read the balance.
`spend_as_of`	When the spend values were last complete.

Money values are strings in US dollars with 6 decimal places. Read them with a decimal type, not a float. The values are for the whole account (scope: "account"). The key object shows which key made the request. Its spend values are null for now.

Get usage

GET /usage

curl "https://api.paretoinference.com/v1/usage?start=2026-09-01&end=2026-10-01&group_by=model" \
  -H "Authorization: Bearer $PARETO_API_KEY"

{
  "object": "usage",
  "scope": "account",
  "currency": "USD",
  "start": "2026-09-01",
  "end": "2026-10-01",
  "group_by": "model",
  "data": [
    {
      "date": "2026-09-26",
      "model": "z-ai/glm-5.3-flash",
      "requests": 1204,
      "input_tokens": 9310221,
      "cached_input_tokens": 7120334,
      "output_tokens": 402113,
      "cost": "0.321441"
    }
  ],
  "total": {
    "requests": 1204,
    "input_tokens": 9310221,
    "cached_input_tokens": 7120334,
    "output_tokens": 402113,
    "cost": "0.321441"
  },
  "next_page": null,
  "as_of": "2026-09-27T20:47:38Z",
  "history_start": "2026-09-24T23:39:48Z"
}

Parameter	Notes
`start`	The first UTC day, as `YYYY-MM-DD`. The default is the first day of the current UTC month.
`end`	The day after the last UTC day, as `YYYY-MM-DD`. The default is tomorrow.
`group_by`	Set to `model` to get one row for each day and model. Without it, you get one row for each day.
`page`	The `next_page` value from the previous response. Send the same `start` and `end`.

Each row gives requests, input_tokens, cached_input_tokens, output_tokens, and cost. Cached input tokens are part of input_tokens. Days without usage do not have a row. A response contains 90 days or fewer. When more days are available, next_page gives the first day of the next page. When next_page is null, you have all the data. Usage history starts at history_start. Pages before that date are empty. Each cost is rounded on its own. The sum of the rows can differ from total.cost in the last digit. The response has an ETag header. Send it back in If-None-Match. If nothing in the response changed, including as_of, the API returns HTTP 304 without a body. as_of moves forward about every 10 seconds, so the ETag changes at least that often.

Freshness

The API reads the balance again after 5 seconds or more.
A request shows in usage after its charges are final. This is usually within 15 seconds after the request ends.
Usage and cost go on the UTC day when the request started.
as_of tells you when the data was last updated.

Rate limits

Each key can send 20 requests each minute to each endpoint, with a burst of 5. Responses to requests with a valid key have these headers. A 503 may not have them.

Header	Meaning
`x-ratelimit-limit`	The requests allowed each minute.
`x-ratelimit-remaining`	The requests you can send now.
`x-ratelimit-reset`	The seconds until the limit is full again.

If you send too many requests, the API returns HTTP 429 with a Retry-After header. Wait that number of seconds before you try again. To show a balance in an app, request it one time each minute or less.

Errors

An error response has error.message, error.type, and error.code. A 400 also names the parameter in error.param.

Status	Code	Cause
400	`invalid_parameter`	A parameter is unknown, repeated, or not valid. The `param` field names it.
401	`401`	The API key is missing, not valid, blocked, or expired.
404	`no_credit_account`	The key is not connected to a credit account.
429	`429`	Too many requests. Wait for the `Retry-After` time.
503	`503`	The data is temporarily not available. Wait for the `Retry-After` time. The API does not return a zero balance in this case.

Get started

Integrations

Reference

Get the balance

Get usage

Freshness

Rate limits

Errors

​Get the balance

​Get usage

​Freshness

​Rate limits

​Errors

Get the balance

Get usage

Freshness

Rate limits

Errors