---
title: budget()
slug: budget
docTags: 
createdAt: 2026-10-19T09:10:00.530Z
---

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()`](https://docs.charthop.com/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.