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.
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:
429with{"error": {"type": "insufficient_quota", "code": "budget_exceeded"}},x-should-retry: false(the OpenAI SDKs don't retry) andx-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 orpricing:.
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, spendtoday,last_7_daysandmonthby 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/usageandvenom usageread 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.windowis 1m to 31d (1h,24h,7d);recentat most 100. The CLI's/routesandvenom routesread 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).
Related
- Admin API for spend, cache and pricing reports.
- Profiles, side requests and gears for a key's default profile.