> Create and manage spend caps and alerts. # 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** ```json { "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` | ## See also - [Budgets (concept)](/docs/concepts/budgets) - [Cost optimization guide](/docs/guides/cost-optimization)