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

# Balance and usage

> What a call costs, when money moves, and how to read a key's spending.

Amounts are in **USD**, the currency the ledger charges in. Every amount carries
a decimal `amount` and the exact integer `amount_micro_usd`, so you never have
to trust a rounding.

## What a call costs

The price in `GET /v2/sources/{id}` is what the buyer pays: the source's price
with the Apiosk fee already in it. There is no separate orchestration charge —
the sum of `usage.sources[].cost` equals `usage.cost` for every run.

## How money moves

1. **Approve.** The plan's maximum cost is checked against the key's
   per-request limit, its monthly limit and the organisation's balance.
2. **Reserve.** Before a source is called, its cost is reserved on the balance.
3. **Run.** The source is called.
4. **Settle.** The actual cost is charged and the remainder released.

A call that fails is refunded. A call whose outcome is unknown stays held until
it is reconciled, and is never charged twice. Because the reservation happens
before the provider is called, a balance can never go negative.

## Balance

```http theme={null}
GET /v2/balance
```

Requires `billing:read`.

```json theme={null}
{
  "organisation_id": "0d2a…",
  "balance": { "available": { "amount": 47.82, "amount_micro_usd": "47820000", "currency": "USD" } },
  "key": { "id": "8c41…", "name": "Nomi Production", "scopes": ["sources:read"], "expires_at": "2027-09-22T16:41:08Z" },
  "limits": {
    "per_request": { "amount": 2, "amount_micro_usd": "2000000", "currency": "USD" },
    "monthly": { "amount": 100, "amount_micro_usd": "100000000", "currency": "USD" },
    "month_spent": { "amount": 0.54, "amount_micro_usd": "540000", "currency": "USD" },
    "month_remaining": { "amount": 99.46, "amount_micro_usd": "99460000", "currency": "USD" },
    "month_start": "2026-09-01T00:00:00Z"
  }
}
```

The balance is the organisation's and is shared by all of its keys. The limits
are this key's alone.

## Usage

```http theme={null}
GET /v2/usage?limit=50
```

Requires `billing:read`. Returns what this key spent this month and its most
recent charges, newest first.

| Query parameter | Type          | Default | Meaning                    |
| --------------- | ------------- | ------- | -------------------------- |
| `limit`         | integer 1–200 | 50      | How many charges to return |

```json theme={null}
{
  "key_id": "8c41…",
  "organisation_id": "0d2a…",
  "month_start": "2026-09-01T00:00:00Z",
  "month_spent": { "amount": 0.54, "amount_micro_usd": "540000", "currency": "USD" },
  "charges": [
    {
      "id": "c19f…",
      "status": "charged",
      "cost": { "amount": 0.023, "amount_micro_usd": "23000", "currency": "USD" },
      "created_at": "2026-09-22T16:58:11Z",
      "source_id": "kvk",
      "operation": "company_registry.search",
      "name": "Company search",
      "run_id": "6f0b…"
    }
  ]
}
```

<ResponseField name="charges[].status" type="string">
  `charged` is settled money. `reserved` is held for a call in flight.
  `refunded` was given back and counts against nothing.
</ResponseField>

<ResponseField name="charges[].run_id" type="string">
  The run that produced the charge; read it back with `GET /v2/runs/{id}`.
</ResponseField>

## Topping up

Balances are funded in the app, under **Organisation → Billing**. An
organisation's main balance is separate from any workspace budget: API keys
spend the main balance only.

| Status | Code                 | Meaning                                                  |
| ------ | -------------------- | -------------------------------------------------------- |
| 200    | —                    | The balance or usage                                     |
| 401    | `invalid_api_key`    | See [Authentication](/api/authentication)                |
| 403    | `insufficient_scope` | The key lacks `billing:read`                             |
| 403    | `api_key_required`   | `GET /v2/usage` is per key; people read usage in the app |