Buying capacity
Allocations
The live, metered form of an agreement: quota, holds, rate limits, delivery window and states.
On this page
An allocation is a block of capacity carved out for one buyer: the contracted tokens, the delivery window and the rate limits from the agreement. It's the thing API keys are bound to and the thing every request is metered against.
What it holds
| Field | Meaning |
|---|---|
| Quota | Contracted input and output tokens |
| Used | Tokens the provider reported, booked against the quota |
| Held | Tokens reserved by requests still running |
| Remaining | Quota minus used minus held, never below zero |
| Window | When requests are served |
| Limits | Requests per minute, tokens per minute and max concurrency |
Input and output are tracked separately. Running out of either one stops the allocation.
States
| State | Meaning | Serves requests |
|---|---|---|
reserved | The quote was accepted. The agreement isn't active yet | No |
ready | Activated, but the window hasn't started | No |
active | Inside the window and serving | Yes |
paused | The supplier or Cairva operations paused it, with a reason | No |
depleted | The input or output allowance is fully used. The agreement completes | No |
expired | The window ended | No |
terminated | The agreement was cancelled before activation | No |
A ready allocation becomes active on the first request after its window opens, or when the background sweep reaches it. When the window ends, a ready, active or paused allocation becomes expired and its agreement completes.
Pausing
The supplier or Cairva operations can pause a ready or active allocation with a written reason, for example to investigate a compromised key or a delivery problem. The buyer is notified with that reason, and requests fail with allocation_paused. Resuming puts the allocation back to active, or ready if its window hasn't started.
Low allowance
When less than 10% of the output allowance remains, the buyer organization gets a notification once for that allocation.
Using it
- Create keys in API keys in the workspace. See API keys.
- Try prompts in the workspace Playground. Playground requests go through the same gateway and spend the same allowance.
- Read it from code with .
- Read per-request usage with .