Balance and usage
Understand the available balance, token prices and the cost of a workload.
One model balance for the team
Hosted model requests use the team’s USD balance across its Spaces and agents. The same balance applies whether a task starts in the dashboard, SDK or HTTP API. Available credit excludes amounts temporarily reserved for running requests.
How a generation charge is calculated
Input and output tokens have separate rates. Use the rates displayed for your selected model. Input includes the assembled instructions, included context, task input and schema or action descriptions — not just the message your application supplied.
charge = (input tokens × input price per million
+ output tokens × output price per million) / 1,000,000When a model reports cached input or cache writes, those categories use their applicable rates instead of the ordinary input rate. The request keeps its pricing snapshot; later price changes do not reprice old requests. Charges are rounded up to microdollars.
Estimate a workload
Enter the displayed model rates and an expected token count for the complete request. The starting rates below are an arithmetic example, not a quote for a particular model.
Generation only. Excludes caching adjustments, repair attempts and separate embedding usage.
A reservation is not a charge
Before dispatching generation, NullProtocol reserves enough available balance for the request. Once usable provider usage is reported, it settles the actual charge and releases the remaining reservation. Concurrent requests share the available balance.
A request can be refused with spend_cap_reached while the displayed balance is still positive: some funds may be reserved, or the remaining amount may not cover the new reservation. Reduce the task or its output limit when appropriate, wait for running requests, or arrange more credit. There is no automatic overdraft.
What happens when a task fails
| Situation | Accounting |
|---|---|
| Refused before generation | No generation charge for that attempt |
| The model answered, but the operation rejected its output | Reported generation usage can still be charged |
| A reply needed a repair attempt | Each dispatched, reported generation request contributes usage |
| Provider outcome or usage is unknown | Marked unknown; the current gateway does not settle a customer charge for that unknown outcome |
| An HTTP request is replayed with the same idempotency key and body | The stored result is returned without another generation request |
Generation usage appears in result.usage; missing usage is not proof that no work occurred. Use the recorded Charged amount in Usage to reconcile the actual balance, rather than estimating a debit from a missing token count.
Knowledge has a separate token count
Preparing documents and embedding a search query use embedding tokens, reported separately from generation. Query usage is in result.knowledgeUsage; the library shows preparation and search totals. The current Knowledge implementation records embedding usage and does not debit those tokens through the generation balance ledger.
Selected passages become part of the generation input, and those input tokens use the selected generation model’s rate. Do not add raw embedding tokens to generation tokens and multiply them by the same price.