get_budget_vs_actual
What it does
Section titled “What it does”Share of each category’s budget spent in a month, to see what is over or close.
Use it for “am I over budget?” or “which categories are nearly used up?”. Give month as the first day of a month, YYYY-MM-01; any other day is refused. ‘current’ is the month in progress, where a share under 100 may only mean the month is not over. Amounts in currency units, spending as a positive number; utilization_pct above 100 means over budget. carried_over says what the months before left in the category, so budgeted plus carried_over is what the month had to spend: a category can be over its budget and still have something left. For what is still available in each category use get_category_balances; for the month’s totals, get_monthly_summary; for the months before, get_spending_trends. One YNAB request; changes nothing.
Behaviour
Section titled “Behaviour”| Kind | read-only |
| Confirmation | no |
| Undo | no |
| Idempotent | yes |
| YNAB requests | 1 for the example below, on a cold cache |
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
plan_id |
string | yes | — | YNAB plan id or ‘last-used’. |
month |
string | no | "current" |
ISO month ‘YYYY-MM-01’ or ‘current’. |
Returns
Section titled “Returns”array of object
| Field | Type | Description |
|---|---|---|
id |
string | YNAB id of the category. |
name |
string | Category name. |
group |
string | Name of the category’s group, e.g. Fun for Tennis. |
budgeted |
number | Amount assigned to the category this month. |
carried_over |
number | What the months before left available in the category when this one started; zero when the category started the month on nothing. |
actual |
number | Amount spent this month, as a positive number. |
balance |
number | What is left: budgeted minus spent, plus what was carried over; negative when overspent. |
utilization_pct |
number | Spent as a share of budgeted, in percent; above 100 means overspent, 0 when nothing is budgeted. |
Example
Section titled “Example”Arguments:
{ "plan_id": "demo-budget", "month": "2026-09-01"}Answer on the demo budget:
[ { "id": "cat-rent", "name": "Rent", "group": "Bills", "budgeted": 950.0, "carried_over": 0.0, "actual": 950.0, "balance": 0.0, "utilization_pct": 100.0 }, { "id": "cat-power", "name": "Electricity", "group": "Bills", "budgeted": 64.2, "carried_over": 0.0, "actual": 64.2, "balance": 0.0, "utilization_pct": 100.0 }, { "id": "cat-internet", "name": "Internet", "group": "Bills", "budgeted": 29.99, "carried_over": 0.0, "actual": 29.99, "balance": 0.0, "utilization_pct": 100.0 }, { "id": "cat-phone", "name": "Phone", "group": "Bills", "budgeted": 19.99, "carried_over": 0.0, "actual": 19.99, "balance": 0.0, "utilization_pct": 100.0 }, "… 8 more"]Errors
Section titled “Errors”month must be 'current' or the first day of a month as YYYY-MM-01, got '{month}'.
YNAB’s own errors come back as Error calling tool '<tool>': YNAB <status>: <detail>.
See also
Section titled “See also”Unofficial project. We are not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. The official YNAB website can be found at https://www.ynab.com. The names YNAB and You Need A Budget, as well as related names, tradenames, marks, trademarks, emblems, and images are registered trademarks of YNAB. avenir-mcp is provided as is, without warranty, and is not financial advice. Legal notice · Privacy