# Budgets

What a budget watches, how its spend and forecast are computed, when it alerts, and why a budget can guard nothing.

A budget is an amount in euro cents for a period (monthly, quarterly or annual), a scope, and the
percentages of the amount at which it alerts. A budget never stops or pauses anything by itself; a
budget with an action proposes stopping resources, and a person approves (see
[Let a budget propose stopping resources](stop-resources-with-a-budget.md)).

## What a budget counts

| Scope                  | Counts                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| The whole organization | Every usage record of the organization                                                                             |
| A project              | The resources that live in the project, as they are moved in and out                                               |
| A saved view           | The resources the saved view's tag query selects now; editing the view changes the budget                          |
| Resources with a tag   | Resources matching 1–10 tag clauses, all of which must match; a clause without values matches any value of the key |

Over the API the scopes are `organization`, `resourceProject`, `project` (a saved view) and `tags`.
A resource without the scope's tags is not counted: untagged is not the same as zero. Registry and
Git storage is metered for the whole organization, not per resource, so only a budget for the whole
organization counts it; the **Budgets** page says how much a narrower budget leaves out.

A budget can also count only some services (`serviceFilter`). Several budgets may cover the same
resource; each is evaluated on its own.

## Periods

Months, quarters and years start at midnight German time on the 1st, the same moment as the
invoice's billing period. Spend is summed from the usage records of the current period.

## When a budget alerts

Once an hour, at five minutes past, every budget is evaluated. For each threshold the spend has
reached, an alert is recorded once per period: it never fires again for that threshold in that
period, even after you change the amount, and the next period starts clean. The alert records the
spend, the amount and what the scope selected at that moment.

A monthly budget can also alert on its forecast (`forecastThresholds`): spend so far, plus what is
billing now at its current rate for the rest of the month, plus usage-based charges at the average
of the last seven days. Forecast and actual thresholds fire independently.

Each new alert:

- is shown on the **Budgets** page under "Fired this period";
- is sent as the event `Budget Threshold Crossed` (source `ews.billing`, `detail.kind` `actual` or
  `forecast`) to the organization's default event bus, where an event rule can route it;
- is e-mailed to the budget's notification addresses, if it has any.

A budget whose scope points at a project or saved view that no longer exists has a broken scope: it
is evaluated as spending nothing and fires no alert.

## A budget that guards nothing

A scope that selects nothing looks like a scope that guards something until the period ends. The
**Budgets** page and `GET /billing/api/budgets/status` say when a budget's scope selects no billable
resource. Check a scope while you create the budget (see [Create a budget](create-a-budget.md)).

## Limits

- At most 10 tag clauses per scope, and 10 forecast thresholds.
- Thresholds are whole percentages from 1 to 1000.
- The number of budgets is a quota (see [Quotas](quotas.md)).

## Related

- [Create a budget](create-a-budget.md)
- [Monitoring budgets and reports](monitoring.md)
