> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costgraph.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Budgets

> Set a spending limit on any slice of your spend and get alerted before you cross it

A budget is a spending limit for one month, quarter, or year, on all your spend
or a filtered slice of it. CostGraph tracks spend against the budget, forecasts
where the period ends, and alerts the budget's owners when spend crosses a
threshold or the forecast says it will.

You manage budgets through the [CostGraph API](/api-reference/costgraph/introduction)
as a signed-in member of the tenant. API keys and third-party app tokens can't
manage budgets. Graph AI and the [MCP server](/costgraph/mcp/usage) can read
them.

## Create a budget

Send `POST /api/v1/tenant/budgets` with your tenant in the
`X-CostGraph-Tenant-ID` header:

```shell theme={null}
curl https://api.costgraph.ai/api/v1/tenant/budgets \
  -H "Authorization: Bearer $COSTGRAPH_TOKEN" \
  -H "X-CostGraph-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production AWS",
    "filters": ["provider:aws", "tag:env:production"],
    "period": "monthly",
    "amount": 25000,
    "currency": "USD",
    "thresholds": [50, 80, 100],
    "forecastAlert": true
  }'
```

The following table describes each field:

| Field | Required | Default | Meaning |
| - | - | - | - |
| `name` | Yes | | Up to 200 characters |
| `period` | Yes | | `monthly`, `quarterly`, or `annual` |
| `amount` | Yes | | The limit for one period, greater than zero |
| `currency` | Yes | | The currency the spend in scope is billed in, such as `USD` |
| `filters` | No | All spend | Up to 50 filters, in the same `key:value` form as cost queries. Virtual tags work too |
| `layer` | No | `billed` | `billed` for your bills, `allocation` for Kubernetes allocation, or `ci` for CI spend |
| `basis` | No | `gross` | `gross` counts spend before credits; `net` subtracts credits |
| `thresholds` | No | `[50, 80, 100]` | Up to 10 percentages of the amount, each up to 1000 |
| `forecastAlert` | No | `true` | Alert when the forecast reaches the amount |
| `ownerUserIds` | No | None | Up to 50 people who receive this budget's alerts |

To change a budget, send the whole budget again with `PUT
/api/v1/tenant/budgets/{id}`. `DELETE` archives it. `GET
/api/v1/tenant/budgets/{id}/series` returns cumulative daily spend against a
straight-line budget for the current period, for charting.

## Periods

Periods are calendar periods in UTC: the calendar month, the calendar quarter
starting in January, April, July, or October, or the calendar year. Spend
resets at the start of each period.

## Status

Every budget response includes an `evaluation` for the current period:
`actual` spend, `pctUsed`, the period-end `forecast`, and a `status`:

* `on_track`: spend and forecast are both under the amount.
* `at_risk`: spend is under the amount, but the forecast reaches it.
* `over`: spend has reached the amount.

CostGraph re-evaluates budgets each time new cost data arrives, usually once a
day.

## Currency

A budget counts spend in its own currency only. If spend in its scope is billed
in a different currency, CostGraph rejects the budget and names the currency to
use. Spend in other currencies that matches the filters is listed in
`excludedCurrencies` and left out of the total.

## Alerts

CostGraph alerts once for each threshold spend crosses in a period, and once
when the forecast first reaches the amount. If spend drops more than five
points back below a threshold, that threshold can alert again.

| Alert | Severity |
| - | - |
| Spend crosses 100% or more | Critical |
| Spend crosses 80% or more | Warning |
| Spend crosses a lower threshold | Info |
| The forecast reaches the amount | Warning |

Budget alerts go to the budget's owners and to your organization owners and
admins by email. Route `cost.budget_threshold` and `cost.forecast_breach` to an
[alert destination](/costgraph/alerts/destinations) to send them to Slack,
Teams, PagerDuty, or a webhook.

## Next steps

<Card title="Forecast" icon="chart-line" href="/costgraph/budgets/forecast">
  How CostGraph forecasts where the period ends.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.