multi-router.aidocs

Budgets & Spend Control

Budgets APIEnterprise

Creating, reading, changing and deleting budgets with the /v1/budgets endpoints.

The budgets endpoints manage an organization's budgets with an API key, for teams that keep budgets in code or read their status from monitoring. Amounts are integers in millionths of a US dollar, so 5000000000 is $5,000. The full list of endpoints, fields and errors is on Budgets in the API Reference.

Endpoints

The main endpoints and the scope each needs:

MethodPathDescriptionScope
POST/v1/budgetsCreate a budget. Accepts dry_run and an Idempotency-Key.budgets:write
GET/v1/budgetsList budgets, with limit up to 200 and cursor.budgets:read
GET/v1/budgets/{id}Read one budget with its current status.budgets:read
PATCH/v1/budgets/{id}Change the fields sent. Accepts dry_run.budgets:write
DELETE/v1/budgets/{id}Delete a budget. Accepts dry_run.budgets:delete
POST/v1/budgets/{id}/model-capsAdd a model cap.budgets:write
POST/v1/budgets/{id}/alertsAdd an alert.budgets:write
POST/v1/budgets/{id}/overridesRaise a cap for the current period.budgets:write
POST/v1/budgets/{id}/budget-requests/{request_id}/approveApprove a budget request.budgets:write

Creating a budget

A budget is created with its scope, period, caps and alerts in one request:

A Tag rules budget with alertsbash
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" }] }
    ]
  }'

The body has these fields:

FieldDescription
nameRequired.
scopeRequired. Exactly one of {"organization":true}, {"routers":[{"router_id","cap_micros"}]} or {"tags":[{"tag","cap_micros"}]}, where a tag's cap applies to each router with the tag.
periodRequired. {"kind":"daily"}, weekly, monthly or lifetime.
total_cap_microsOptional total cap.
model_capsOptional list of a model slug and cap.
alertsOptional alerts: threshold_percent above 0 up to 200, watches, optional projected_within_minutes, and actions.
timezoneOptional. Defaults to UTC.
enabledOptional. Defaults to true.

watches is {"kind":"total"}, {"kind":"per_router"}, {"kind":"per_model"}, or {"kind":"model","model":"…"}. The recipient of an email is the address of a person active in the organization. Actions are {"kind":"block"}, {"kind":"send_email","recipient":"…"} and {"kind":"send_webhook","endpoint_id":"…"}. The response is 201 with organization_id and the budget in data, a Location header and the budget's ETag. After creation, model caps and alerts change through their own endpoints, conditional on the budget's ETag.

Reading status

GET /v1/budgets/{id} includes a status object for the current period, with 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. A new budget's status is null for its first few seconds, until Multi-Router first computes it.

Errors

The budgets endpoints return these errors:

ErrorStatusCause
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.
insufficient_scope403The API key lacks the scope.
budget_not_found404No budget with that id exists in the organization.
budget_policy_managed409The budget belongs to a tools policy.
budgets_off404Budgets are off for the installation.
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.
version_conflict412The If-Match ETag is stale. The response carries the current budget.
When a Budget BlocksOverview
Was this helpful?