> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynito.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get balance

> Read your organization's available balance with administrative API credentials.

`GET /api/v1/billing/balance` returns the authenticated organization's available balance and top-up amounts. All amounts are integer USD nanos serialized as strings: `1000000000` is \$1. Keep them as strings or use integer arithmetic such as JavaScript `BigInt`.

## Authentication

Use an API key with `admin: true` whose owner is currently an organization owner or admin. An OAuth bearer with `cli:inference` also works when its user is a current owner or admin. Ordinary inference keys and browser cookies alone cannot read this endpoint. See [API keys](/api/api-reference/api-keys) to provision an admin key.

The credential determines the organization. Optional `X-Org-ID` must match it; query parameters and request bodies cannot select another organization.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://app.trynito.ai/api/v1/billing/balance \
  -H "Authorization: Bearer $NITO_ADMIN_API_KEY"
```

`X-API-Key` is also accepted. The read does not require a funded balance, a subscription, unused key spend-cap budget, or available inference capacity. Its own management request limits still apply.

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "available_nanos": "28500000000",
  "top_up_projection_state": "available",
  "top_up_remaining_nanos": "1500000000",
  "top_up_spent_nanos": "500000000"
}
```

| Field | Meaning |
| - | - |
| `available_nanos` | Available organization balance, \$28.50 in this example. |
| `top_up_projection_state` | `available` when top-up attribution can be returned; `unavailable` when that calculation fails. |
| `top_up_remaining_nanos` | Remaining top-up balance; omitted when the projection is unavailable. |
| `top_up_spent_nanos` | Known spending attributed to top-ups, not total historical spend across all funding sources; omitted when unavailable. |

If top-up attribution fails, HTTP `200` still returns the ledger balance:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "available_nanos": "28500000000",
  "top_up_projection_state": "unavailable"
}
```

Do not turn omitted top-up fields into zero. A missing balance account returns zero amounts with projection state `available`; a ledger outage returns `503`, not a fabricated zero balance. Responses use `Cache-Control: no-store`.

## Errors and limits

* `401`: missing, expired, revoked, or invalid credentials.
* `403`: insufficient admin authority or an organization mismatch.
* `429`: the balance read's management request limit was exhausted; honor `Retry-After` when supplied.
* `503`: billing is disabled or a required dependency is unavailable.

Management reads are rate-limited separately from inference and do not reserve inference concurrency slots. A balance is a snapshot, not authorization for a future model call.

## Usage history

This endpoint does not return request history, provider costs, or margins. A public billing-usage history endpoint is not available yet. Use response `usage` data and the [developer console](https://app.trynito.ai/api) for usage history. See [Get usage](/api/api-reference/usage/get-usage).

## Related

* [Balance endpoint schema](/api/api-reference/endpoints/billing/balance)
* [Funding and billing](/api/api-reference/funding-and-billing)
* [Rate limits](/api/api-reference/errors-and-rate-limits/rate-limits)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.