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
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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
Export a budget's Excel workbook
Credential: a company's API key or OAuth token.
The budget as the Excel workbook the app's Download button gives: one row per
account (and dimension value), one column per accounting period, figures in the
company's base currency. Edit the figures and send the file back to
POST /api/v1/budgets/{budgetId}/excel.
Keep the workbook's hidden sheet: it identifies the budget, its accounting year and the figures the file was exported with, which is how an upload tells a figure you changed from one somebody else changed in the meantime.
Required Scope
budgets-read
path Parameters
budgetIdThe budget id
Export a budget's Excel workbook › Responses
The budget workbook (.xlsx)
Overwrite a budget's figures from an edited workbook
Credential: a company's API key or OAuth token.
Upload an edited copy of the budget's workbook (from
GET /api/v1/budgets/{budgetId}/excel) as the multipart form field file,
up to 5 MB. The figures in the file become the budget's figures, exactly as
the app's Upload button publishes them: only the figures typed into the file
change, and formula figures that read them recalculate. The upload is kept in
the budget's upload history with its file.
Pass ?dryRun=true to check the file first: the response is the same, with
every figure that would change and every row that is refused, and nothing is
written. Pass the dry run's previewToken to the publish to have it refused
with 409 BUDGET_EXCEL_PREVIEW_STALE if the budget changed in between.
A workbook from another budget, accounting year or currency is refused with
400, and so is a publish with refused rows (BUDGET_EXCEL_HAS_REFUSED_ROWS)
or with no figure to change (BUDGET_EXCEL_NOTHING_TO_PUBLISH). A dry run
answers those rows in refusedRows instead.
A retry sent with the same x-api-idempotency-key is answered with the
original response. Use a new key for each request: a dry run and the publish
after it are two requests.
Required Scope
budgets-write
path Parameters
budgetIdThe budget id
query Parameters
dryRuntrue checks the workbook and answers every figure it would change, writing nothing. Omitted or false, the workbook is published over the budget's figures.
previewTokenThe previewToken a dry run of the same file answered. Given, the publish is refused with 409 BUDGET_EXCEL_PREVIEW_STALE if the budget changed after that dry run.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Overwrite a budget's figures from an edited workbook › Request Body
fileThe edited budget workbook (.xlsx), up to 5 MB.
Overwrite a budget's figures from an edited workbook › Responses
The changes the workbook makes, and the published upload unless it was a dry run
dryRunThe workbook was only checked; nothing was written.
budgetIdbudgetNameaccountingYearStartDateFirst day of the budget's accounting year, YYYY-MM-DD
accountingYearEndDateLast day of the budget's accounting year, YYYY-MM-DD
currencyISO 4217 currency every amount is in — the company's base currency, which the workbook states too.
fileNameThe name the uploaded file carried
exportedAtWhen the workbook was exported (ISO 8601)
rowsReadAccount rows read from the workbook
Every figure that changes, or changed: the figures typed into the workbook and the formula figures that recalculate because of them. A dry run and the publish of the same file answer the same changes.
Rows the workbook is refused for. Any refused row blocks publishing.
ignoredColumnsColumn headers that match no accounting period of the budget. Their cells change nothing.
ignoredRowNumbersRows that carry figures but no account number. They change nothing.
canPublishNo row is refused and at least one figure changes, so publishing succeeds.
previewTokenIdentifies this file against the budget as it stood when read. Pass it to the publish of the same file to have the publish refused if the budget changes in between.
publicationThe published upload, kept in the budget's upload history with its file. null on a dry run.
List a budget's frozen baselines
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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.