API reference

Current allocation

GET /v1/allocations/current: quota, usage, holds, remaining allowance, window and enforced limits.

On this page

Example
Response
Fields

Returns the live state of the allocation your key belongs to: entitlement, what's used, what's held by running requests, what remains, the window and the enforced limits.

GET/v1/allocations/current

Requires the usage:read scope.

Example

curl https://cairva.xyz/v1/allocations/current \
  -H "Authorization: Bearer $CAIRVA_API_KEY"

const res = await fetch("https://cairva.xyz/v1/allocations/current", {
  headers: { Authorization: `Bearer ${process.env.CAIRVA_API_KEY}` },
});
const allocation = await res.json();
console.log(allocation.remaining, allocation.window.expires_at);

import os
import requests

res = requests.get(
    "https://cairva.xyz/v1/allocations/current",
    headers={"Authorization": f"Bearer {os.environ['CAIRVA_API_KEY']}"},
)
allocation = res.json()
print(allocation["remaining"], allocation["window"]["expires_at"])

Response

JSON

{
  "id": "ALC-4K7Q2M",
  "agreement": "AGR-9T3D1X",
  "state": "active",
  "service_mode": "sandbox",
  "capacity_type": "METERED_ALLOWANCE",
  "model": "gemma4:e2b",
  "window": { "starts_at": "2026-11-01T00:00:00.000Z", "expires_at": "2026-12-01T00:00:00.000Z" },
  "quota": { "input_tokens": 1000000, "output_tokens": 500000 },
  "used": { "input_tokens": 31, "output_tokens": 18, "requests": 1 },
  "held": { "input_tokens": 0, "output_tokens": 0 },
  "remaining": { "input_tokens": 999969, "output_tokens": 499982 },
  "limits": { "requests_per_minute": 60, "tokens_per_minute": 100000, "max_concurrency": 4 }
}

The numbers above are an example. Your allocation's values come from its agreement.

Fields

Field	Meaning
`id`	The allocation reference shown in the workspace, such as `ALC-4K7Q2M`
`agreement`	The agreement reference
`state`	`reserved`, `ready`, `active`, `paused`, `depleted`, `expired` or `terminated`. See Allocations
`service_mode`	`live` or `sandbox`
`capacity_type`	`METERED_ALLOWANCE`, `RESERVED_THROUGHPUT` or `DEDICATED_WINDOW`
`model`	The model id this allocation covers
`window`	Start and end of delivery, ISO 8601 in UTC
`quota`	Contracted input and output tokens
`used`	Booked tokens and the number of completed requests
`held`	Tokens held by requests that are running or waiting on usage
`remaining`	`quota` minus `used` minus `held`, never below zero
`limits`	The three rate limits the gateway enforces

Note

id here is the human-readable reference. The allocation_id in a chat completion's cairva object is the allocation's UUID. Both identify the same allocation.

requests counts requests that finished, including ones still waiting on usage. Failed requests aren't counted.