# Create a budget

> Create a Budgets budget with the CLI, the API or Python, choosing its period, the spending it counts and the thresholds that send alerts.

This guide creates a monthly budget of 1000 for compute spending, with one threshold that alerts
when 80% is spent and another that warns when the month is forecast to go over. For a shorter
first run, see [Get started](/budgets/get-started).

## Before you begin

* Sign in with the [CLI](/developer/cli), get a
  [token](/identity/get-a-token) for the API, or create the
  [Python client](/budgets/guides/use-the-python-client).
* Create at least one confirmed [notification channel](/budgets/concepts/notification-channels). The
  CLI refers to channels by name. The API and Python client use their IDs, which
  `openstack budget channel list` shows.

## 1. Choose the period and amount

Pick a `period` of `daily`, `monthly`, `quarterly` or `yearly` for a budget that resets, or
`custom` for one fixed span. The `amount` is per window and is a decimal string in the API.
For a custom period, also set its start and end:

```sh
openstack budget create launch-quarter \
  --amount 5000 \
  --period custom \
  --start 2026-11-01 \
  --end 2027-02-01 \
  --threshold name=warn,value=80,channel=finance
```

## 2. Choose what counts

Leave out the filter to count everything in the project. To count only some spending, filter by
service (`compute`, `volume`, `image`), region, or usage type. This guide counts compute only.

## 3. Create the budget with its thresholds

A budget needs between one and ten [thresholds](/budgets/concepts/thresholds). Each names a level, what it
compares, and the channels it alerts.

<CodeBlockTabs defaultValue="CLI">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="CLI">
      CLI
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="API">
      API
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Python">
      Python
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="CLI">
    ```sh
    openstack budget create compute-monthly \
      --amount 1000 \
      --period monthly \
      --service compute \
      --threshold name=warn,value=80,channel=finance \
      --threshold name=overrun,value=100,basis=forecasted,channel=finance
    ```
  </CodeBlockTab>

  <CodeBlockTab value="API">
    ```sh
    curl --request POST https://budget.public.global.vexxhost.net/v1/budgets \
      --header "X-Auth-Token: $TOKEN" \
      --header "Content-Type: application/json" \
      --data '{
        "name": "compute-monthly",
        "amount": "1000",
        "period": "monthly",
        "filter": {"services": ["compute"]},
        "thresholds": [
          {"name": "warn", "basis": "actual", "unit": "percentage", "value": "80",
           "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]},
          {"name": "overrun", "basis": "forecasted", "unit": "percentage", "value": "100",
           "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]}
        ]
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Python">
    ```python
    budget = budgets.budgets.create(
        name="compute-monthly",
        amount="1000",
        period="monthly",
        filter={"services": ["compute"]},
        thresholds=[
            {"name": "warn", "basis": "actual", "unit": "percentage", "value": "80",
             "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]},
            {"name": "overrun", "basis": "forecasted", "unit": "percentage", "value": "100",
             "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]},
        ],
    )
    ```
  </CodeBlockTab>
</CodeBlockTabs>

On the CLI, `basis` defaults to `actual` and `unit` to `percentage`. The API and Python client
need both fields on every threshold.

The API answers `201 Created` with the budget:

```json
{
  "id": "c7e1a5b3-9d2f-4e8c-a6b4-1f3d5e7c9a2b",
  "name": "compute-monthly",
  "project_id": "a6f1c2d93b8e4f07b5d4e2c1a9f8e7d6",
  "enabled": true,
  "amount": "1000",
  "currency": "USD",
  "period": "monthly",
  "filter": {"services": ["compute"]},
  "thresholds": [
    {"name": "warn", "basis": "actual", "unit": "percentage", "value": "80",
     "comparison": "greater_than_or_equal", "enabled": true,
     "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]},
    {"name": "overrun", "basis": "forecasted", "unit": "percentage", "value": "100",
     "comparison": "greater_than_or_equal", "enabled": true,
     "channels": ["3f9c1e7a-2b4d-4c6e-8a1f-5d7b9e2c4a6f"]}
  ],
  "revision": 1,
  "created_by": "4c8e2f1a9b7d4e6f8a3c5b1d7e9f2a4c",
  "created_at": "2026-10-07T14:10:27Z",
  "updated_at": "2026-10-07T14:10:27Z",
  "status": null
}
```

`status` is `null` until Budgets first checks the budget, within about an hour.

## 4. Verify

After the first check, the budget reports its spending and each threshold's state:

```sh
openstack budget list
```

```
+--------------------------------------+-----------------+----------------------------------+---------+--------+----------+------------------+-------------------+---------+---------+
| ID                                   | Name            | Project ID                       | Period  | Amount | Currency | Actual Spend     | Forecast Spend    | Alarms  | Enabled |
+--------------------------------------+-----------------+----------------------------------+---------+--------+----------+------------------+-------------------+---------+---------+
| c7e1a5b3-9d2f-4e8c-a6b4-1f3d5e7c9a2b | compute-monthly | a6f1c2d93b8e4f07b5d4e2c1a9f8e7d6 | monthly | 1000   | USD      | 248.731250000000 | 1155.164285714286 | overrun | True    |
+--------------------------------------+-----------------+----------------------------------+---------+--------+----------+------------------+-------------------+---------+---------+
```

Here the project has spent about 249 of its 1000, but the month is forecast to cost about 1155,
so the `overrun` threshold is in alarm and has alerted the `finance` channel.

## Next steps

* [Receive alerts with a webhook](/budgets/guides/receive-webhook-alerts) to send alerts to chat or your own
  systems.
* [Change a budget](/budgets/guides/change-a-budget) when the amount or thresholds need adjusting.
* Look up every option in the [CLI reference](/budgets/cli) or the
  [API reference](/budgets/api).