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:
| Method | Path | Description | Scope |
|---|---|---|---|
| POST | /v1/budgets | Create a budget. Accepts dry_run and an Idempotency-Key. | budgets:write |
| GET | /v1/budgets | List 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-caps | Add a model cap. | budgets:write |
| POST | /v1/budgets/{id}/alerts | Add an alert. | budgets:write |
| POST | /v1/budgets/{id}/overrides | Raise a cap for the current period. | budgets:write |
| POST | /v1/budgets/{id}/budget-requests/{request_id}/approve | Approve a budget request. | budgets:write |
Creating a budget
A budget is created with its scope, period, caps and alerts in one request:
The body has these fields:
| Field | Description |
|---|---|
name | Required. |
scope | Required. 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. |
period | Required. {"kind":"daily"}, weekly, monthly or lifetime. |
total_cap_micros | Optional total cap. |
model_caps | Optional list of a model slug and cap. |
alerts | Optional alerts: threshold_percent above 0 up to 200, watches, optional projected_within_minutes, and actions. |
timezone | Optional. Defaults to UTC. |
enabled | Optional. 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:
| Error | Status | Cause |
|---|---|---|
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. |
insufficient_scope | 403 | The API key lacks the scope. |
budget_not_found | 404 | No budget with that id exists in the organization. |
budget_policy_managed | 409 | The budget belongs to a tools policy. |
budgets_off | 404 | Budgets are off for the installation. |
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. |
version_conflict | 412 | The If-Match ETag is stale. The response carries the current budget. |