# Allocations

> The live, metered form of an agreement: quota, holds, rate limits, delivery window and states.

Source: https://cairva.xyz/docs/allocations

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](https://cairva.xyz/docs/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 [`GET /v1/allocations/current`](https://cairva.xyz/docs/allocation-status).
- Read per-request usage with [`GET /v1/usage`](https://cairva.xyz/docs/usage).