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
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/budgets | List budgets. Paginated. | budgets:read |
| POST | /v1/budgets | Create 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-caps | List model caps. | budgets:read |
| POST | /v1/budgets/{id}/model-caps | Add a cap for one model. Returns 201. | budgets:write |
| PATCH | /v1/budgets/{id}/model-caps | Change the cap_micros of the model named in ?model=. | budgets:write |
| DELETE | /v1/budgets/{id}/model-caps | Remove the cap of the model named in ?model=. | budgets:delete |
| GET | /v1/budgets/{id}/alerts | List alerts. | budgets:read |
| POST | /v1/budgets/{id}/alerts | Add 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-events | List the current period's alert firings. | budgets:read |
| GET | /v1/budgets/{id}/overrides | List the current period's overrides. | budgets:write |
| POST | /v1/budgets/{id}/overrides | Raise a cap for the current period: cap_micros, with an optional router_id and model. Returns 201. | budgets:write |
| PATCH | /v1/budgets/{id}/overrides | Change the cap_micros of the override selected by ?router_id= and ?model=. | budgets:write |
| DELETE | /v1/budgets/{id}/overrides | Remove the override selected by ?router_id= and ?model=. | budgets:delete |
| GET | /v1/budgets/{id}/budget-requests | List 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}/approve | Approve a pending request with the cap_micros to grant. | budgets:write |
| POST | /v1/budgets/{id}/budget-requests/{request_id}/deny | Deny 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
| Field | Type |
|---|---|
name | string, required |
| The budget name. | |
scope | object, required |
Exactly one of {"organization": true}, {"routers": [{"router_id", "cap_micros"}]} or {"tags": [{"tag", "cap_micros"}]}. Replaced whole by PATCH. | |
period | object, required |
{"kind": "daily"}, weekly, monthly or lifetime. Replaced whole by PATCH. | |
total_cap_micros | integer or null |
| The total cap. | |
model_caps | array |
| On create, a model slug and cap_micros for each capped model. | |
alerts | array |
| On create, the alerts. | |
timezone | string |
| The timezone the period resets in. Defaults to UTC. | |
enabled | boolean |
| 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.
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
| Code | Status | Meaning |
|---|---|---|
invalid_budget | 400 | A field is missing or invalid. The message names it. |
invalid_scope | 400 | The scope does not hold exactly one of organization, routers or tags. |
invalid_threshold | 400 | An alert threshold is out of range or has more than two decimal places. |
unknown_model | 400 | A model cap names a model absent from the catalog. |
budget_not_found | 404 | No budget with that id exists in the organization. |
budget_item_not_found | 404 | The budget has no such model cap or alert. |
override_not_found | 404 | No override matches the router and model. |
budget_request_not_found | 404 | No budget request has that id. |
budgets_off | 404 | Budgets are off for the installation. |
budget_policy_managed | 409 | The budget belongs to a tools policy. |
model_cap_exists | 409 | The model already has a cap. |
override_exists | 409 | An override for that router and model already exists. |
request_not_pending | 409 | The budget request was already decided. |
request_period_closed | 409 | The budget request's period has ended. |
use_sub_collection | 400 | A 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_unavailable | 503 | The model catalog could not be read to check model caps. Retry. |