--- title: budgetJob() slug: budgetjob docTags: createdAt: 2026-10-19T09:10:01.052Z --- 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', '').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()`](https://docs.charthop.com/budget).