Concepts
Billing and the ledger
There are two books. What the platform bills you is the capacity and the services your projects use — compute, storage, conversations and a few more, never your model tokens. What your users owe you is a separate ledger the platform keeps on your behalf, in US dollars, and nothing about it reaches your invoice from us.
None of it is on by default
An agent with no prices charges nobody, and a user with no wallet spends your balance rather than theirs. You can switch this on for one agent and one user while everything else carries on unchanged.
A hold, not a charge
Nothing on this platform runs on credit. Before a run makes its first model call, a deposit is reserved against whoever is paying for it. The run is metered as it goes, the real cost is settled once, and whatever the deposit over-reserved is released.
A deposit is not a ceiling. It is topped up in steps of the same size as the run spends, so it only has to be a sensible first step rather than a prediction — which is just as well, because nobody knows what a request will cost until it has cost it.
held is not spent
A run in flight has reserved what it expects to need and has not been charged yet, which is what explains a balance that looks lower than you expect mid-conversation. It can grow during a long run as the reservation is topped up, and it returns to zero when the run settles. Render available, not balance, if a run might be in flight.
A run that fails — a model error, a tool that raised, a crash in the runner — is released rather than settled, so the payer is not charged for it. A run whose pod dies outright cannot release anything; its hold is reclaimed by a sweep once it expires, typically within half an hour, so nothing leaks — but until then a customer's credit is reserved against a run that is over, which can refuse their next run on a tight balance for a reason that has nothing to do with it.
Which account pays
One field decides it. Invoke with end_user_id — which needs a credential with the admin role — and the named user's wallet pays, if the agent is priced and they have one; leave it out and the run belongs to your own credential and spends your tenant balance.
| Your tenant account | A user's wallet | |
|---|---|---|
| Denominated in | tokens — quota, not money | micro-USD — real money |
| Paid by | a run with no end_user_id | a run naming that user |
| Topped up by | us, against your plan | you, with credits |
| Who owns the run | your credential | that user |
The denomination belongs to the account, so a wallet figure is money
A hold's settled amount is in its account's own unit. On a wallet that is micro-USD, so it equals the charge exactly and is not a token count — charting it under an axis labeled “tokens” draws fractions of a cent for every wallet-funded run. Token counts live in the usage reports; a hold's units are not one.
Naming a user changes more than who pays: they own the conversation, a tool confirmation goes to them rather than to you, and their own autonomy policy applies. That is what you want for a consumer product — the person approving a refund is the person it affects.
Your backend will not receive that run's events
They are addressed to the end user, not to your service user, so the socket to watch them on is the one their browser opens with a ticket. A backend that invokes and watches in one process sees nothing and looks broken.
What a price is made of
You declare prices in your agent's manifest, in US cents per million tokens, and each class of token is multiplied by its own rate:
charge = input_tokens_not_cached × input_token_cost
+ cached_tokens × cached_input_token_cost
+ output_tokens × output_token_cost
───────────────────────────────────────────────── ÷ 1,000,000Everything is an integer and the total is floored, so rounding always lands in your user's favor and a very short turn can legitimately cost nothing. Nothing on the money path is a float, so nothing drifts.
Cached tokens are a discount, not an extra charge
Providers report cached prompt tokens as part of the prompt count rather than beside it. So the billable input is prompt − cached at your input rate, plus the cached remainder at your cached rate. Set the cached rate below the input rate and a returning user pays less; set it above and they pay more for a cache hit than a miss, which is the opposite of a discount.
Tokens cannot answer “what did this tool cost me” — a tool calling a paid third-party API costs the same whether the turn was 50 tokens or 5,000. So a tool call can be priced directly, per call, and the price may be an expression over the call's own arguments: $0.30 + 2.9% capped at $5 is writable, and min is how you write the cap. Reasoning tokens are billed as output.
A SKU is the label your agent's holds and charges are recorded against, named in its manifest. The name you choose is scoped to your project: the ledger stores it as <tenant>/<project>/<sku>, so two customers who both call something premium never share a row, and the whole stored code is capped at 64 characters. A name nobody has used before is registered the first time a run uses it, so a typo is a new SKU rather than an error — it charges correctly and reports under a name you did not mean. The platform's own SKUs, below, are the platform's, and the same for everybody.
What the platform bills you
Capacity and platform services, metered per project and priced by a rate card you can read and cannot set. It does not scale with tokens, because we never see your model bill: you bring your own provider key and your provider invoices you directly. Your floor is their price list; the margin above it is yours. The usage page groups every charge into these families:
| Category | What is counted |
|---|---|
| Compute | the CPU and memory each pod reserves, by the hour, whether or not it is busy. Disk is recorded and not charged. |
| Storage | the bytes your files and your agents' conversation databases hold, per GiB held per hour |
| Conversations | each turn appended — an invocation, an answer to a paused workflow, creating or deleting a conversation — and each conversation read back |
| Approvals | each approval or confirmation put to a person, and each decision recorded on one, including a policy deciding automatically |
| Observability | each run recorded, and each run, trace or series read back |
| Wallets | wallet creations, operations on a wallet, and wallet reads |
| Event stream | each open socket, by the connection-hour — an idle tab left open counts |
| Builds | each deploy that reached the build, the builder's time, and each image scanned |
A wallet call that is refused — an unknown wallet, a closed one, a zero adjustment — is never billed, and creating a wallet that already exists is free, so calling create on every sign-in costs nothing extra.
When a user cannot run
| What they see | What happened | What fixes it |
|---|---|---|
| “…the account balance is too low.” | Out of credit. | Credit the wallet. |
| “This account is not currently able to make requests.” | Frozen or closed. | Unfreeze it. |
Two messages because the remedies differ — telling somebody whose account you suspended to top it up sends them to do the one thing that cannot help. Freezing keeps the balance, so use it to stop spending without touching the money; closing needs a zero balance, so refund or write off what is left first and there is always a transaction saying where a customer's money went.
A balance can go slightly negative, on purpose
A refusal lands on the next model call, not the one in flight, so a run can exceed a balance by at most one call's cost. We charge what was actually used rather than pretending otherwise. A priced tool widens that gap, because one call can cost several times the deposit — which is the argument for capping anything priced from its own arguments.
Where to go next
The wallets API is every route for creating a wallet, crediting it and reading a statement, plus your own balance and usage. Authentication covers the credential that may write them and the ticket that may not, and autonomy is the other thing naming an end user changes. Charging your users sets all of this up end to end, and the usage API reads what the platform has charged you.