budget()
Returns a budget, so you can use its amount, usage, dates, and other details in a formula.
Syntax
budget(budget)
Parameters
Parameter | Type | Description |
|---|---|---|
budget | String | The budget's slug (for example 'eng-fy26') or its ID. |
Returns
A budget object. Read its values with a property, like budget('eng-fy26').amount. Returns blank if the budget doesn't exist or you don't have access to it.
Properties
Property | Returns |
|---|---|
amount | The budget amount as of the formula's date. If the amount was changed (re-baselined), you get the amount in effect on that date. |
usage | The budget's Amount Used as of the formula's date. Same number shown on the budget's detail page. Its meaning follows the budget's cost basis (see below). |
forecastlanding | The forecast value the budget is tracking toward as of the formula's date (the dashed line on the Budget Usage Over Time chart). See below. |
label | The budget's name. |
slug | The budget's slug. |
id | The budget's ID. |
status | DRAFT, ACTIVE, or ARCHIVED. |
startdate | The first day of the budget period. |
enddate | The last day of the budget period. |
owner | The first budget owner (a person). |
owners | All budget owners (a list of people). |
groups | The groups (for example departments) the budget covers. |
costexpr | The budget's custom cost calculation, if it has one. |
createuser, createat | Who created the budget, and when. |
updateuser, updateat | Who last updated the budget, and when. |
How cost basis affects usage and forecastlanding
| Total cost over period | Annualized |
|---|---|---|
usage | Total cost that falls between the budget's start and end dates. Run-rates are prorated by month, and open jobs count from their planned start date. | Yearly run-rate of everyone in scope as of the formula's date. Open jobs count at their full run-rate. |
forecastlanding | Cumulative cost from the budget start through the formula's date (capped at the end date). It rises over the period and equals usage at the end of the period. $0 before the period starts. | Yearly run-rate as of the formula's date, where open jobs only count once their planned start date has passed. It steps up over the period and reaches usage once every open job has started. |
Examples
- Budget amount: budget('eng-fy26').amount
- Amount used: budget('eng-fy26').usage
- Amount remaining: budget('eng-fy26').amount - budget('eng-fy26').usage
- Percent used: budget('eng-fy26').usage / budget('eng-fy26').amount
- Amount used as of a past date: asof('2026-06-30', {budget('eng-fy26').usage})
- Budget name: budget('eng-fy26').label
Good to know
- Per-job values: budget() gives budget-wide totals. For one job's share of a budget, use budgetJob().
- Scenarios: usage and forecastlanding are calculated from your primary org data, not from scenario changes.
- Access: if you can't see the budget, the formula returns blank.