> ## Documentation Index > Fetch the complete documentation index at: https://docs.paretoinference.com/llms.txt > Use this file to discover all available pages before exploring further. # Balance and usage > Read your credit balance and usage with your API key. 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 ` | | 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` ```bash theme={"system"} curl https://api.paretoinference.com/v1/balance \ -H "Authorization: Bearer $PARETO_API_KEY" ``` ```json theme={"system"} { "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` ```bash theme={"system"} curl "https://api.paretoinference.com/v1/usage?start=2026-09-01&end=2026-10-01&group_by=model" \ -H "Authorization: Bearer $PARETO_API_KEY" ``` ```json theme={"system"} { "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. |