# Create a hard or soft dollar budget

`POST /v1/budgets`

**In this build:** Real.

**Scope:** `billing.write`

**CLI:** `harebox budget new`

Send an `Idempotency-Key` header. A retry with the same key never repeats the action.

## Request: `BudgetInput`

| Field | Type | Notes |
|---|---|---|
| `limit_usd` (required) | `number` |  |
| `scope` | `string` | account, project:ID, fleet:ID or label:KEY=VALUE. |
| `period` | `string` | One of: `day`, `week`, `month` |
| `include_ai` | `boolean` |  |
| `action` | `string` | sleep and stop both save the disk and stop what the budget covers, since a sleeping sandbox is still billed; sleep is kept for older clients. One of: `alert`, `sleep`, `stop`, `block_new_starts` |
| `alert_at_percent` | `array` |  |

## Response: 201

`Budget`

`Budget`

Errors follow [one format](../errors.html).