/api/finance/budget-status endpoint compares each department’s actual expense against its budgeted amount for a single calendar month, returning the variance and percentage of budget consumed. It is designed for “which department is over budget?” and “how much of the Marketing budget is left?” questions. An important constraint is that this endpoint covers exactly one month at a time — it joins the budgets table (which stores one row per department per month) against actual transaction spend for that month, so there is no multi-month aggregation or annual roll-up.
Request
string
required
Any date within the target month in
YYYY-MM-DD format. The query truncates this date to the first of the month internally, so 2025-06-15, 2025-06-01, and 2025-06-30 all return June 2025 data.string
Optional comma-separated list of department names to include in the response (e.g.
Engineering,Marketing). Whitespace around commas is trimmed automatically. When omitted, all departments are returned.Response
The response is an array ofBudgetRow objects, one per department (or per filtered department if departments was supplied).
string
The department name.
number
The budgeted expense amount for this department for the month.
number
The actual total expense recorded for this department during the month.
number
The difference between actual and budget:
actual - budget. A positive variance means the department spent more than budgeted (over budget); a negative variance means it spent less (under budget).number
The fraction of the budget consumed:
actual / budget. A value of 1.0 means exactly 100% of the budget was used; 1.08 means 8% over budget; 0.944 means the department used only 94.4% of its budget.This endpoint covers a single month only. There is no multi-month or annual budget aggregation. Pass any date within the target month —
2025-06-15 and 2025-06-01 both return June 2025.