Skip to content
Docs menu

Keys, budgets and limits

Mint client keys, limit what each may call and spend, cap intents and teams, and let each key read its own usage and routing.

View .md

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

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

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), and provider limits are handled by rate shaping (Configuration reference).

Spend 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).

Intent spend accounts

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.

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

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

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).