Budgets
Read-only access to budgets & forecasting: budget grids per account and period, scenarios, budget-vs-actuals comparison, variance vs frozen baselines, and the cash runway headline. Requires the Budgets license.
List budgets
Retrieves a paginated list of your company's budgets. Each budget plans one
accounting year; amounts are kept in the company's base currency (currency).
Pass ?status= to filter by budget status, ?accountingYearId= to filter
by accounting year, or ?search= to prefix-match on budget name.
Required Scope
budgets-read
query Parameters
pagePage number (1-indexed)
limitMaximum number of items per page
searchPrefix search on budget name
statusFilter by budget status
accountingYearIdFilter by accounting year
sortByField to sort by
sortOrderSort direction
List budgets › Responses
Paginated list of budgets for the company
Page of budgets
totalTotal number of matching budgets
pageCurrent page number
limitItems per page
totalPagesTotal number of pages
Get a budget
Retrieves a budget with its full grid: budget cells (lines), the accounting
year's periods, driver rows, and per-budget display metadata.
Cells in CLOSED periods carry the book actuals rather than the planned amount
(source: ACTUALS) — the same rolling-forecast view the app shows. The
planned amounts for closed periods are preserved internally but are not part
of this response.
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
query Parameters
includeBaselineWhen true, every line also carries baseline — the prior accounting year's realised amount for the same account and calendar month (decimal string; 0.00 when no prior-year figure exists).
Get a budget › Responses
Budget detail with lines and periods
idThe unique identifier of the budget
nameBudget name
statusBudget status. Informational — the status does not restrict reads.
accountingYearIdAccounting year the budget covers
accountingYearStartDateAccounting year start date (ISO date, YYYY-MM-DD)
accountingYearEndDateAccounting year end date (ISO date, YYYY-MM-DD)
currencyISO 4217 currency every amount on this budget is denominated in — the company's base (functional) currency.
createdAtWhen the budget was created (ISO 8601)
updatedAtWhen the budget was last updated (ISO 8601)
Budget cells (one per account × period, and per dimension bucket when dimensioned)
The accounting year's periods, ordered by periodIndex
Driver rows with resolved cells (non-money quantities)
Budget-local display overrides. Only accounts carrying an override are listed.
Stable #N row numbers used by formula references. Rows never numbered in the editor may be absent.
dimensionCategoryIdDimension category scoping this budget: lines then carry per-dimension-value buckets. null for flat budgets.
Get the budget vs actuals comparison
Budget vs booked actuals per account and period, with a summary. Variance is
budget − actual; isOverBudget marks the unfavourable direction per
account type (overspend on expense accounts, shortfall on revenue accounts).
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
query Parameters
viewModeView mode: FISCAL_YEAR compares the budget's accounting year; ROLLING_12_MONTHS compares 12 months from startMonth (or the current month).
startMonthStart month for the rolling view (YYYY-MM)
Get the budget vs actuals comparison › Responses
Budget vs actuals comparison
budgetNameBudget name
currencyISO 4217 currency every amount is denominated in — the company's base (functional) currency.
Summary totals for the comparison
Comparison entries by account and period
The periods covered by the comparison
List a budget's frozen baselines
Immutable snapshots of the resolved grid, frozen at a point in time. The variance report compares actuals against one of these.
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
List a budget's frozen baselines › Responses
The budget's frozen baselines
The budget's frozen baselines, most recent first
Get a frozen baseline with its snapshot cells
Retrieves one frozen baseline including every snapshot cell.
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
baselineIdThe frozen baseline id
Get a frozen baseline with its snapshot cells › Responses
Frozen baseline detail
idThe unique identifier of the frozen baseline
labelLabel given when the baseline was frozen
frozenAtWhen the baseline was frozen (ISO 8601)
currencyISO 4217 currency every amount is denominated in — the company's base (functional) currency.
Snapshot cells
scenarioIdScenario whose overlay was snapshotted. null = the base grid.
frozenByIdentity that froze the baseline
List a budget's re-baseline proposals
When an accounting period closes, the system can propose re-baselining the budget's remaining months off the closed actuals. Proposals are confirmed or rejected in the app; this lists them with their status.
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
List a budget's re-baseline proposals › Responses
The budget's re-baseline proposals
The budget's re-baseline proposals
List a budget's scenarios
Scenarios are assumption overlays (driver-cell overrides and line toggles) on
top of the budget's base grid. The isBaseline "Base" scenario represents
the grid with no overlay; it is created when the tenant first uses scenarios
in the app, so a budget that has never opened the scenario switcher returns an
empty list — the base data is the budget detail itself.
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
List a budget's scenarios › Responses
The budget's scenarios
The budget's scenarios
Resolve a budget's grid under a scenario
Returns the fully resolved grid (budget cells + driver rows) with the scenario's assumptions applied. Read-only — nothing is persisted.
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
scenarioIdThe scenario id
Resolve a budget's grid under a scenario › Responses
The resolved scenario grid
currencyISO 4217 currency every amount is denominated in — the company's base (functional) currency.
All resolved budget cells under the scenario overlay
All driver rows with resolved cells under the overlay
hasCycleTrue when the overlay could not resolve because of a formula cycle — offending cells carry error: BUDGET_FORMULA_CYCLE and amounts must not be trusted.
forecastHorizonMonthLast calendar month (YYYY-MM) with a subscription-forecast projection. Cells past it that reference the subscription forecast resolve to 0. null when no subscription token is used.
Get the variance report vs a frozen baseline
Closed-period actuals compared against a frozen baseline (defaults to the most
recently frozen one). Variance is actual − frozen baseline — the inverse of
the comparison endpoint, which compares against the live plan. Returns an
empty data array when the budget has no frozen baseline yet.
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
query Parameters
frozenBaselineIdFrozen baseline to compare against. Defaults to the most recently frozen baseline.
Get the variance report vs a frozen baseline › Responses
Variance rows vs the frozen baseline
currencyISO 4217 currency every amount is denominated in — the company's base (functional) currency.
Closed-period variance rows vs the frozen baseline. Empty when the budget has no frozen baseline yet.
Get the runway headline
Cash-on-hand, trailing 3-month burn, and months of runway remaining. This is company-wide (cash and burn are properties of the whole company, not of one budget), which is why it is not scoped under a budget id.
Required Scope
budgets-read
query Parameters
asOfISO date (YYYY-MM-DD) the cash and burn are computed as of. Defaults to today.
Get the runway headline › Responses
Runway headline for the company
currencyISO 4217 currency every amount is denominated in — the company's base (functional) currency.
cashOnHandSum of bank-account-linked ledger balances as of asOf (decimal string)
trailing3MonthBurnTrailing average net outflow over the last 3 closed months (decimal string). Negative when the company is cash-positive.
monthsRemainingCash divided by burn; null = infinite runway (burn ≤ 0)
statusOK (≥ 6 months), WATCH (3-6), LOW (< 3), or UNKNOWN (no cash source, or no closed periods to compute burn from — see hasCashSource).
hasCashSourceWhether at least one bank account is linked to a ledger account. When false, cashOnHand is a meaningless 0.
asOfISO date the cash and burn were computed as of
feedReportedCashTotalSum of provider-reported balances over active bank accounts in the functional currency (decimal string). null when any active account is held in another currency.
unlinkedBankAccountCountActive bank accounts with no linked ledger account — invisible to cashOnHand.