Budgets

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 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 can read them.

Create a budget

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

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 to send them to Slack, Teams, PagerDuty, or a webhook.

Next steps

Forecast

How CostGraph forecasts where the period ends.

Get Started

CostGraph Operator

CostGraph Agent

GPUs

Insights

Alerts

Budgets & Forecast

Allocation

Virtual Tags

Network

MCP

Slack

Security

Developers

Self-Hosted

Integrations

Changelog

Create a budget

Periods

Status

Currency

Alerts

Next steps

Forecast

​Create a budget

​Periods

​Status

​Currency

​Alerts

​Next steps

Forecast

Create a budget

Periods

Status

Currency

Alerts

Next steps