---
title: Keys, budgets and limits
description: Mint client keys, limit what each may call and spend, cap intents and teams, and let each key read its own usage and routing.
section: orchestrator
order: 70
audience: [operator, builder, agent]
sources: [docs/architecture.md, services/go-orchestrator/AGENTS.md, services/go-orchestrator/internal/server/server.go]
features: [orchestrator.admin-keys, orchestrator.admin-intents, orchestrator.admin-teams, orchestrator.api-usage, orchestrator.api-routing, orchestrator.api-guardrails]
---

Every `/v1` request is made with a client key. The orchestrator uses the key to decide which models the caller may reach, how fast it may call, how much it may spend, which route profile applies and whose spend a request is. An app built on venom typically mints one key per customer or per tenant.

## Mint a key {#create}

```bash
curl -s -X POST http://127.0.0.1:8787/admin/v1/keys \
  -H "Authorization: Bearer $VENOM_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"acme-prod","team":"acme","rpm_limit":120,"tpm_limit":400000,
       "allowed_models":["venom-default","venom-fast","venom-embed"],
       "budget":{"daily_usd":5,"monthly_usd":100},"profile":"qwen-first"}'
```

The answer is the key record plus `key`, the plaintext `vk-…` secret, shown once. The console's Keys page does the same.

| Field | Type | Default | What it does |
|---|---|---|---|
| `name` | string | required | Label in the request log, metrics and spend views. |
| `team` | string ≤ 64 bytes | none | Groups keys in spend views; also the team guardrail rules and intent caps apply to. |
| `allowed_models` | list | all | Aliases and `upstream/model` ids the key may use (`403 model_not_allowed` otherwise). It also limits what `GET /v1/models` lists. |
| `rpm_limit`, `tpm_limit` | int | none | Requests and tokens per minute (token buckets). |
| `budget` | `{daily_usd, daily_soft_usd, monthly_usd, monthly_soft_usd}` | none (unlimited) | USD, 0 to 1e9, 0 = none. A soft limit left out is 80% of that period's hard limit. Periods are UTC days and months. |
| `profile` | profile name | none | The key's default route profile, used when a request sends no `x-venom-profile`. |

| Endpoint | What it does |
|---|---|
| `GET /admin/v1/keys` | Every key with its limits, budget and current daily and monthly spend (`spent_usd`, `reserved_usd`, `state: ok, soft, exceeded, none`, `resets_at`). Keys are listed by an 8-character `prefix`, never in full. |
| `POST /admin/v1/keys` | Mint a key (above). |
| `PATCH /admin/v1/keys/{id}` | Change `team`, `budget` (`null` clears it), `profile` (`""` clears it), `rpm_limit`, `tpm_limit` (0 removes a limit). Spend so far is kept. |
| `DELETE /admin/v1/keys/{id}` | Revoke a key; its spend stays in the ledger. |

The bootstrap key from `VENOM_API_KEY` is listed with `id: "env"` and no prefix; it takes no team or budget (`PATCH` is `400`), but its spend is tracked.

## Rate limits {#rate-limits}

Each request takes one token from the key's RPM bucket. Its estimated size (prompt bytes/4 plus the requested `max_tokens`, `max_completion_tokens` or `max_output_tokens`) is charged to the TPM bucket before forwarding and reconciled to the reported usage afterwards. A request that doesn't fit yet is `429 rate_limit_exceeded` with `Retry-After`; one larger than the whole per-minute limit is `429 tpm_limit_exceeded` with no `Retry-After`. A route's `rate_limit` applies to every key together ([Routes and strategies](/docs/orchestrator/routing.md#keys)), and provider limits are handled by rate shaping ([Configuration reference](/docs/orchestrator/configuration.md#rate-shaping)).

## Spend budgets {#budgets}

Each request is pre-charged its worst-case cost (prompt bytes/4 plus its max output, 4,096 tokens when unset, at the list price of the costliest target it could reach), so concurrent requests can't jointly overshoot. When it ends, the real cost is booked; a stream cut short is booked at an estimate of what was generated.

- Over a hard limit: `429` with `{"error": {"type": "insufficient_quota", "code": "budget_exceeded"}}`, `x-should-retry: false` (the OpenAI SDKs don't retry) and `x-venom-budget-reset: <RFC 3339>`.
- Over a soft limit: served, with `x-venom-budget-warning`.
- A request that can only reach local models costs $0 and is never refused, so local work continues past a budget.
- A key with a hard limit and a cloud target the price table can't price: `403 unpriced_model` (its cost would read $0). Add the model to the price table or `pricing:`.

Budget state is exported as `venom_key_spend_usd`, `venom_key_budget_usd`, `venom_budget_soft_limit_crossed_total` and `venom_budget_exceeded_total` ([Operations](/docs/orchestrator/operations.md#metrics)).

## Intent spend accounts {#intents}

A long-running agent needs a budget per task. A request with `x-venom-intent: <id>` (at most 128 bytes) is metered against that intent and against its key's team. An intent's cap is a running total, not a period.

```bash
curl -s -X PUT http://127.0.0.1:8787/admin/v1/intents/fix-flaky-tests \
  -H "Authorization: Bearer $VENOM_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"cap_usd": 5, "team": "core"}'
curl -s -X PUT http://127.0.0.1:8787/admin/v1/teams/core/intent-cap \
  -H "Authorization: Bearer $VENOM_ADMIN_TOKEN" -H "Content-Type: application/json" -d '{"cap_usd": 50}'
```

| Endpoint | What it does |
|---|---|
| `GET /admin/v1/intents[?state=ok\|uncapped\|exceeded]` | Every intent (`cap_usd`, `spent_usd`, `reserved_usd`, `requests`, `state`, `exceeded_at`) and every team cap, exceeded first. `?state=exceeded` is the feed to alert on. |
| `GET /admin/v1/intents/{id}` | One intent. |
| `PUT /admin/v1/intents/{id}` | Set the cap (0 removes it) and create the account; raising it above the spend clears the exceeded mark. |
| `DELETE /admin/v1/intents/{id}` | Remove it (the team keeps the spend counted). |
| `PUT /admin/v1/teams/{team}/intent-cap` | Cap the total spend of all the team's intents. |

Over a cap: `402` with code `intent_budget_exceeded` and `x-should-retry: false`; the message names the scope (`intent` or `team`). An intent is created by its first request (uncapped) if you haven't made it. More than 100,000 distinct intents is `503 intent_ledger_full`. A malformed header is `400 invalid_intent`.

## A key's own usage and routing {#self-service}

Two endpoints let a key holder see their own figures, and only theirs: neither takes a key parameter.

```bash
curl -s "http://127.0.0.1:8787/v1/usage?sessions=5" -H "Authorization: Bearer $VENOM_API_KEY"
curl -s "http://127.0.0.1:8787/v1/routing?window=24h&recent=10" -H "Authorization: Bearer $VENOM_API_KEY"
```

- `GET /v1/usage[?session=<id>&sessions=5]` (`object: "venom.usage"`): the key's budget state per period, spend `today`, `last_7_days` and `month` by model (local models at $0 with their tokens counted), today's costliest sessions with their subagents rolled in, and one session's figures with `?session=`. The venom CLI's `/usage` and `venom usage` read it.
- `GET /v1/routing[?window=24h&alias=a,b&recent=10]` (`object: "venom.routing"`): for each alias the key used, its targets in order with live state (`ok`, `half_open`, `cooling`, `circuit_open`, `unhealthy`, `missing`, `disabled`), each target's share of requests, latency and TTFT percentiles, why requests fell back, and the latest fallbacks. `window` is 1m to 31d (`1h`, `24h`, `7d`); `recent` at most 100. The CLI's `/routes` and `venom routes` read it.

Both read the request log by key name; if another key has the same name the per-session figures are withheld (`log: false`) rather than mixed. `GET /admin/v1/routing` is the same view over every key.

`GET /v1/guardrails` returns the guardrails that apply to the calling key: the org's and its team's rules with their locks, the key's own, and the catalog. The venom CLI's `/guardrails` reads it. Rules are configured in `guardrails:` ([Configuration reference](/docs/orchestrator/configuration.md#guardrails)).

## Related

- [Admin API](/docs/orchestrator/admin-api.md) for spend, cache and pricing reports.
- [Profiles, side requests and gears](/docs/orchestrator/profiles-and-gears.md#profiles) for a key's default profile.
