---
title: "Update a budget"
method: PUT
path: "/api/v1/budgets/{id}"
tags: ["Cost Controls"]
---

# Update a budget

`PUT /api/v1/budgets/{id}`

## Request

- Base URL: `https://orchestrator.getaxonflow.com`
- URL: `https://orchestrator.getaxonflow.com/api/v1/budgets/{id}`
- Auth: none declared
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/docs/api/v1/budgets/:id/put.ts> (a function with typed inputs; its response is checked against the schema)

Update an existing budget configuration.

Enterprise only. These routes are not registered in Community
edition, which returns 404 Not Found.

## Path parameters

- `id` string, required

## Request body

- BudgetUpdate
  - `name` string
  - `limit_usd` number, double
  - `on_exceed` 'warn' | 'block' | 'downgrade'
  - `alert_thresholds` integer[]

## Response `200`

Budget updated

- Budget
  - `id` string, required: Unique budget identifier
  - `name` string, required: Human-readable budget name
  - `enabled` boolean: When false the budget is configured but its limit is not enforced — usage is still tracked. Lets operators dry-run a budget before flipping it on.
  - `scope` 'organization' | 'team' | 'agent' | 'workflow' | 'user', required: Budget scope level
  - `scope_id` string: ID of the scoped entity (team_id, agent_id, etc.)
  - `limit_usd` number, double, required: Maximum spending limit in USD
  - `period` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly', required: Budget reset period
  - `on_exceed` 'warn' | 'block' | 'downgrade': Action when budget is exceeded
  - `alert_thresholds` integer[]: Percentage thresholds for alerts (e.g., [50, 80, 100])
  - `org_id` string: Organization ID
  - `tenant_id` string: Tenant ID (multi-tenant deployments)
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Invalid budget configuration
- `404`: Budget not found

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/revisions/f408ef3ec9dd?raw)