# Current allocation

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

Source: https://cairva.xyz/docs/allocation-status

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.

```endpoint
GET /v1/allocations/current
```

Requires the `usage:read` scope.

## Example

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

```javascript JavaScript
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);
```

```python Python
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](https://cairva.xyz/docs/allocations#states) |
| `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.