Skip to content

Reference

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.

Without caching · USD
charge = (input tokens × input price per million
        + output tokens × output price per million) / 1,000,000

When 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.

Estimated per task$0.0016
Estimated workload$1.60

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

SituationAccounting
Refused before generationNo generation charge for that attempt
The model answered, but the operation rejected its outputReported generation usage can still be charged
A reply needed a repair attemptEach dispatched, reported generation request contributes usage
Provider outcome or usage is unknownMarked 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 bodyThe 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.