budgetJob()
Returns one job's cost toward a budget. Use it to add budget cost columns to a Data Sheet or to build Smart Calculations. The numbers match the budget's Budget Breakdown Per Job table.
Syntax
budgetJob(budget, [job])
Parameters
Parameter | Type | Description |
|---|---|---|
budget | String | The budget's slug (for example 'eng-fy26') or its ID. |
job | Job, Person, User, or String (optional) | The job to look up. Without it, the formula uses the current row's job. You can pass a job, a person, or a user (for example manager), or a job ID or person ID in quotes. A bare ID is tried as a job first, then as a person. If the value you pass doesn't match anyone in the budget, the result is blank. It does not fall back to the current row. |
Returns
A value with the properties below. Read them with a dot, like budgetJob('eng-fy26').applied.
Properties
Property | Total cost over period budget | Annualized budget |
|---|---|---|
applied | The job's total cost over the budget period. Matches the Total Applied to Budget column. | The job's yearly run-rate as of the formula's date. |
appliedToDate | Cost from the budget start through the end of the month that contains the formula's date. $0 before the period starts; equals applied after it ends. | Blank |
months | The job's cost per month. See "Monthly values" below. | Blank |
annualized | The job's yearly run-rate as of the formula's date. | Same as applied. |
Monthly values
months holds one value per month of the budget period, matching the month columns of the Budget Breakdown Per Job table.
Formula | Returns |
|---|---|
budgetJob('eng-fy26').months['2026-04'] | April 2026. Use the yyyy-MM format ('2026-4' won't match). |
budgetJob('eng-fy26').months[0] | The first month of the period (counting starts at 0). |
budgetJob('eng-fy26').months.first | The first month of the period. |
budgetJob('eng-fy26').months.last | The last month of the period. |
budgetJob('eng-fy26').months.length | The number of months in the period. |
A month outside the budget period returns blank.
Examples
- Job's total cost to the budget: budgetJob('eng-fy26').applied
- Cost so far this period: budgetJob('eng-fy26').appliedToDate
- Remaining cost this period: budgetJob('eng-fy26').applied - budgetJob('eng-fy26').appliedToDate
- April cost: budgetJob('eng-fy26').months['2026-04']
- Yearly run-rate: budgetJob('eng-fy26').annualized
- Cost through June 30, whatever the sheet date: asof('2026-06-30', {budgetJob('eng-fy26').appliedToDate})
- The manager's cost to the budget: budgetJob('eng-fy26', manager).applied
- A specific person's cost: budgetJob('eng-fy26', '<personId>').applied
- Default to zero instead of blank: budgetJob('eng-fy26').applied ?: 0
Where you can use it
- Data Sheet columns: open the budget, select View on Data Sheet, then Add Calculation and enter a formula. Each row shows that job's value.
- Smart Calculations: create a job field with a budgetJob() formula. It can then be shown on the Data Sheet, on profiles, and in reports.
When the result is blank
- The job isn't in the budget's groups.
- You can't see the base compensation for the person in that job.
- You don't have access to the budget, or the budget doesn't exist.
- The formula runs inside a scenario. budgetJob() uses primary org data only.
- The job argument doesn't match a job or person.
- appliedToDate or months on an Annualized budget.
- annualized on an open job that has no price yet (no comp band and no planned comp). Its applied is $0.
- A budget's own cost calculation reads a Smart Calculation that calls budgetJob() on that same budget. The nested call returns blank instead of looping.
Good to know
- appliedToDate counts whole months. On February 14 it includes all of February. This keeps it in line with the monthly columns.
- The date matters. applied on an Annualized budget, appliedToDate, and annualized all depend on the formula's date (the Data Sheet date, or the date used by a report or asof()).
- annualized vs. the breakdown table: on a Total cost over period budget, annualized is the run-rate as of the formula's date. The table's Total Annualized column is taken as of the first month of the period, so the two can differ if comp changed.
- Column totals vs. the breakdown table: the Data Sheet lists jobs as of one date. A job that left the budget's groups partway through the period is in the breakdown table but may not be on the sheet, so a column total can be lower than the table total.
- Performance: the first budgetJob() value for a budget calculates the whole budget, so the first load of a large sheet can take a moment. Later rows and extra columns for the same budget are fast. Results refresh when comp changes, and otherwise within about 5 minutes.
- Reports: a report that uses a Smart Calculation built on budgetJob() may not refresh right away after the budget itself is edited.
- Budget-wide totals: for the whole budget's amount or usage, use budget().