Categories

GET /budgets/{budget_id}/categories

The categories of a budget: its lines. A list, one page at a time.

Categories form a tree: a top-level category can hold sub-categories, which can hold their own. To read a large budget, go one level at a time: first parent_id=none for its top-level categories, then a category's id for the categories under it.

Keys: personal keys only. Other keys get 403 personal_key_required.

The category object

Field	Type	Description
id	string	The category's id.
parent_id	string	The category it belongs to. null for a top-level category.
depth	integer	1 for a top-level category, 2 for one under it, and so on.
name	string
amount	amount	The amount planned for the category, its sub-categories included.
monthly_breakdown	array	That amount per month: month (YYYY-MM) and amount.
spent	amount	The sum of the category's own spent expenses, without its sub-categories'.
committed	amount	The sum of the category's own planned expenses, without its sub-categories'.
branch_spent	amount	Spent by the category and every category under it.
branch_committed	amount	Committed by the category and every category under it.

Amounts are in the budget's currency.

tip

To see how a category is doing, compare its amount with branch_spent and branch_committed: all three cover the whole branch. Don't add a category's amount to its sub-categories': it already includes them.

Parameters

Parameter	In	Type	Description
budget_id	path	string	The budget's id.
parent_id	query	string	A category's id: only the categories right under it. none: only the top-level categories. Left out: every category.
from	query	YYYY-MM	Every monthly_breakdown starts at this month.
to	query	YYYY-MM	Every monthly_breakdown ends at this month. Not before from.
limit	query	integer	Categories per page, from 1 to 200. 50 by default.
cursor	query	string	The next_cursor of the previous page.

from and to only trim the monthly breakdowns: amount, spent and committed always cover the whole budget.

Example

The top-level categories, with their plan for the first quarter:

curl "https://app.spendbaker.com/sb_back/api/v1/budgets/7d2f9a40-3c8e-4b16-a5d7-2e9c0f81b4a3/categories?parent_id=none&from=2026-01&to=2026-03" \
  -H "Authorization: Bearer $SPENDBAKER_KEY"

{
  "data": [
    {
      "id": "c41a8e5b-92d7-4f03-8b6e-1a7d3c5f9e20",
      "parent_id": null,
      "depth": 1,
      "name": "Paid social",
      "amount": "96000.00",
      "spent": "0.00",
      "committed": "0.00",
      "monthly_breakdown": [
        { "month": "2026-01", "amount": "8000.00" },
        { "month": "2026-02", "amount": "8000.00" },
        { "month": "2026-03", "amount": "8000.00" }
      ],
      "branch_spent": "24310.75",
      "branch_committed": "6000.00"
    }
  ],
  "next_cursor": null
}

Then the categories under "Paid social":

curl "https://app.spendbaker.com/sb_back/api/v1/budgets/7d2f9a40-3c8e-4b16-a5d7-2e9c0f81b4a3/categories?parent_id=c41a8e5b-92d7-4f03-8b6e-1a7d3c5f9e20" \
  -H "Authorization: Bearer $SPENDBAKER_KEY"

Errors

400 invalid_limit, 400 invalid_cursor, 401, 403, 429 and 500, as in Errors and limits, and:

Status	code	When
400	invalid_parameter	parent_id is neither a category id nor none, from or to is not YYYY-MM, or from is after to.
404	not_found	No such budget, or it isn't shared with you.