multi-router.aidocs

API Reference

BudgetsEnterprise

Creating, reading, changing and deleting budgets, with their model caps, alerts, overrides and requests.

The budgets endpoints manage an organization's budgets: their scope, period and caps, the alerts that notify or block, and the current period's overrides and budget requests. Amounts are integers in millionths of a US dollar, so 5000000000 is $5,000. Writes take the budget's bdg_ id. See Budgets & Spend Control.

Endpoints

MethodPathDescriptionScope
GET/v1/budgetsList budgets. Paginated.budgets:read
POST/v1/budgetsCreate a budget. Returns 201. Accepts dry_run and an Idempotency-Key.budgets:write
GET/v1/budgets/{id}Get one budget with its current period's status.budgets:read
PATCH/v1/budgets/{id}Change name, enabled, scope, period, total_cap_micros and timezone. Accepts dry_run.budgets:write
DELETE/v1/budgets/{id}Delete a budget. Accepts dry_run.budgets:delete
GET/v1/budgets/{id}/model-capsList model caps.budgets:read
POST/v1/budgets/{id}/model-capsAdd a cap for one model. Returns 201.budgets:write
PATCH/v1/budgets/{id}/model-capsChange the cap_micros of the model named in ?model=.budgets:write
DELETE/v1/budgets/{id}/model-capsRemove the cap of the model named in ?model=.budgets:delete
GET/v1/budgets/{id}/alertsList alerts.budgets:read
POST/v1/budgets/{id}/alertsAdd an alert. Returns 201.budgets:write
PATCH/v1/budgets/{id}/alerts/{alert_id}Change the fields sent.budgets:write
DELETE/v1/budgets/{id}/alerts/{alert_id}Remove an alert.budgets:delete
GET/v1/budgets/{id}/alert-eventsList the current period's alert firings.budgets:read
GET/v1/budgets/{id}/overridesList the current period's overrides.budgets:write
POST/v1/budgets/{id}/overridesRaise a cap for the current period: cap_micros, with an optional router_id and model. Returns 201.budgets:write
PATCH/v1/budgets/{id}/overridesChange the cap_micros of the override selected by ?router_id= and ?model=.budgets:write
DELETE/v1/budgets/{id}/overridesRemove the override selected by ?router_id= and ?model=.budgets:delete
GET/v1/budgets/{id}/budget-requestsList the current period's budget requests.budgets:write
GET/v1/budgets/{id}/budget-requests/{request_id}Get one budget request.budgets:write
POST/v1/budgets/{id}/budget-requests/{request_id}/approveApprove a pending request with the cap_micros to grant.budgets:write
POST/v1/budgets/{id}/budget-requests/{request_id}/denyDeny a pending request. The body is {}.budgets:write

Model cap and alert writes are conditional on the budget's ETag and take no dry_run. Override and request writes act on the current period and take no If-Match or dry_run. An override with neither router_id nor model applies to the total cap. Override and approval caps are from 1 to 9223372036854775807.

Creating a budget

A budget on routers tagged productionbash
curl -X POST https://api.multi-router.ai/v1/budgets \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "scope": { "tags": [{ "tag": "production", "cap_micros": 2000000000 }] },
    "period": { "kind": "monthly" },
    "total_cap_micros": 5000000000,
    "model_caps": [{ "model": "anthropic/claude-opus-5", "cap_micros": 1000000000 }],
    "alerts": [
      { "threshold_percent": 80, "watches": { "kind": "total" },
        "actions": [{ "kind": "send_email", "recipient": "lead@example.com" }] },
      { "threshold_percent": 100, "watches": { "kind": "per_router" },
        "actions": [{ "kind": "block" }] }
    ]
  }'
FieldType
namestring, required
The budget name.
scopeobject, required
Exactly one of {"organization": true}, {"routers": [{"router_id", "cap_micros"}]} or {"tags": [{"tag", "cap_micros"}]}. Replaced whole by PATCH.
periodobject, required
{"kind": "daily"}, weekly, monthly or lifetime. Replaced whole by PATCH.
total_cap_microsinteger or null
The total cap.
model_capsarray
On create, a model slug and cap_micros for each capped model.
alertsarray
On create, the alerts.
timezonestring
The timezone the period resets in. Defaults to UTC.
enabledboolean
Defaults to true.

An alert has threshold_percent, above 0 and up to 200 with at most two decimal places, watches, an optional projected_within_minutes, and actions. watches is {"kind":"total"}, {"kind":"per_router"}, {"kind":"per_model"} or {"kind":"model","model":"…"}. Actions are {"kind":"block"}, {"kind":"send_email","recipient":"…"} and {"kind":"send_webhook","endpoint_id":"…"}. Each alert gets a bdr_ id.

Raise this period's total capbash
curl -X POST https://api.multi-router.ai/v1/budgets/bdg_8Wq3Ld5TnM/overrides \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cap_micros": 7500000000 }'

Status

A budget's status describes the current period: spend_micros, cap_micros, remaining_micros, burn_rate_micros_per_min, projected_cap_at, label, what is restricted, and unpriced_share. label is ok, nearing, imminent or capped. Status is null until Multi-Router first computes it, and always null in the current object of a 409 or 412 response.

Errors

CodeStatusMeaning
invalid_budget400A field is missing or invalid. The message names it.
invalid_scope400The scope does not hold exactly one of organization, routers or tags.
invalid_threshold400An alert threshold is out of range or has more than two decimal places.
unknown_model400A model cap names a model absent from the catalog.
budget_not_found404No budget with that id exists in the organization.
budget_item_not_found404The budget has no such model cap or alert.
override_not_found404No override matches the router and model.
budget_request_not_found404No budget request has that id.
budgets_off404Budgets are off for the installation.
budget_policy_managed409The budget belongs to a tools policy.
model_cap_exists409The model already has a cap.
override_exists409An override for that router and model already exists.
request_not_pending409The budget request was already decided.
request_period_closed409The budget request's period has ended.
use_sub_collection400A PATCH sends model_caps, alerts or overrides, which change through their own endpoints. The valid field of the error lists the endpoint path template, such as /v1/budgets/{id}/alerts; {id} is not replaced with the object id.
catalog_unavailable503The model catalog could not be read to check model caps. Retry.
API TokensAgents
Was this helpful?