---
title: "Create a budget"
method: POST
path: "/api/v1/budgets"
tags: ["Cost Controls"]
---

# Create a budget

`POST /api/v1/budgets`

## Request

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

Create a new budget with spending limits. Budgets can be scoped to
organization, team, agent, workflow, or user level.

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

## Headers

- `X-Org-ID` string, required

## Request body

- BudgetCreate
  - `id` string, required
  - `name` string, required
  - `scope` 'organization' | 'team' | 'agent' | 'workflow' | 'user', required
  - `scope_id` string
  - `limit_usd` number, double, required
  - `period` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly', required
  - `on_exceed` 'warn' | 'block' | 'downgrade'
  - `alert_thresholds` integer[]

## Response `201`

Budget created

- 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
- `409`: Budget with this ID already exists

---

[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)