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

# Billing

> What each call costs, when it is charged, and how reservations work.

Prices are in tokens. A call is charged its price when its job ends with:

* an answer, with or without people in it (an empty circle and an `UNRESOLVED` resolve included);
* `404 person_not_found`;
* a partial answer (the research of a requested type failed).

It is charged whether or not the answer is read. A job that fails, or ends in any other error, is not charged its price.

> [!NOTE]
>
> `404 person_not_found` is an error, and is charged: the job ran to its end.

| Operation | Price, tokens |
| - | - |
| `/v1/resolve` | 0.002 |
| `/v1/circle` | 0.004 |
| `/v1/edge` | 0.002 |
| `/v1/paths` | 0.008 |

`/v1/job`, `/v1/balance` and `/v1/openapi.json` are free.

A call that starts a job reserves from the balance, before the job starts:

* its price;
* on circle, edge and paths with `on_miss: RESEARCH`, `max_tokens` on top (`2` when absent).

A call is never charged more than it reserved; what is not charged returns to the balance when the job ends. A balance that does not cover the reservation is answered `402 insufficient_balance`; an account with no billing account yet, `402 billing_account_missing` (creating the first API key opens it).

On the answers of a call that reserved, except a `503` whose reservation was returned:

* `X-Orbb-Reserved` carries the tokens the call reserved;
* `X-Orbb-Balance` carries the tokens available after the reservation.

Amounts have at most 3 decimals.

`/v1/balance` reads the balance; its `low_balance` is true when less than 25 tokens are available.


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