Budgets API

Budgets enforce spending limits across org, project, tag, or end-user scopes. Cap breaches can alert, auto-downgrade, or block.

List budgets

GET /manage/v1/budgets

Get a budget

GET /manage/v1/budgets/{budget_id}

Returns the budget config, current spend, and period bounds.

Create a budget

POST /manage/v1/budgets

Request body

{
  "name": "Q2 production cap",
  "scope": {
    "type": "project",
    "project_id": "proj_01HXY..."
  },
  "cap_usd": 500,
  "period": "monthly",
  "action_at_cap": "auto_downgrade",
  "downgrade_to": "@cheap"
}

Valid scope.type: org, project, tag, end_user. Valid action_at_cap: alert, block, auto_downgrade.

Update a budget

PATCH /manage/v1/budgets/{budget_id}

Delete a budget

DELETE /manage/v1/budgets/{budget_id}

Reset a budget

POST /manage/v1/budgets/{budget_id}/reset

Clears current-period spend without waiting for the next reset date. Useful after resolving a cost anomaly.

Alerts

GET    /manage/v1/budgets/{budget_id}/alerts
POST   /manage/v1/budgets/{budget_id}/alerts
DELETE /manage/v1/budgets/{budget_id}/alerts/{alert_id}

Each alert specifies a threshold percentage (e.g. 80) and one or more channels (email, webhook).

Events

GET /manage/v1/budgets/{budget_id}/events

Returns the history of threshold crossings, cap actions, and resets.

MCP tools

Tool	Maps to
`list_budgets`	`GET /manage/v1/budgets`
`get_budget`	`GET /manage/v1/budgets/{id}`
`create_budget`	`POST /manage/v1/budgets`
`update_budget`	`PATCH /manage/v1/budgets/{id}`
`delete_budget`	`DELETE /manage/v1/budgets/{id}`
`reset_budget`	`POST /manage/v1/budgets/{id}/reset`
`list_budget_alerts`	`GET /manage/v1/budgets/{id}/alerts`
`create_budget_alert`	`POST /manage/v1/budgets/{id}/alerts`
`delete_budget_alert`	`DELETE /manage/v1/budgets/{id}/alerts/{aid}`
`list_budget_events`	`GET /manage/v1/budgets/{id}/events`