Budgets

A budget is an amount planned over a period, in one currency, split into categories: its lines. Its expenses are what was spent or committed against it.

You see the budgets shared with you, as in the app.

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

The budget object

Field	Type	Description
id	string	The budget's id.
name	string
description	string	Empty when there is none.
status	string	draft, active, completed or archived.
currency	string	The budget's currency, an ISO 4217 code. Every amount of the budget is in it.
total	amount	The budget's amount.
spent	amount	The sum of its expenses whose status is spent.
committed	amount	The sum of its expenses whose status is planned.
start_at	timestamp	When the budget's period starts.
end_at	timestamp	When the budget's period ends.

What is left to spend is total - spent - committed. Cancelled expenses count nowhere.

List budgets

GET /budgets

The budgets shared with you, whatever their status. A list, one page at a time.

Parameters

Parameter	Type	Description
limit	integer	Budgets per page, from 1 to 200. 50 by default.
cursor	string	The next_cursor of the previous page.

Example

curl https://app.spendbaker.com/sb_back/api/v1/budgets \
  -H "Authorization: Bearer $SPENDBAKER_KEY"

{
  "data": [
    {
      "id": "7d2f9a40-3c8e-4b16-a5d7-2e9c0f81b4a3",
      "name": "Marketing 2026",
      "description": "Paid acquisition and events",
      "status": "active",
      "currency": "EUR",
      "total": "240000.00",
      "spent": "61250.40",
      "committed": "18000.00",
      "start_at": "2026-01-01T00:00:00Z",
      "end_at": "2026-12-31T00:00:00Z"
    }
  ],
  "next_cursor": null
}

Errors

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

Get a budget

GET /budgets/{budget_id}

One budget, with its plan per month and all its categories, every level.

A large budget can have hundreds of categories. To read it one level at a time, use GET /budgets/{budget_id}/categories instead.

Parameters

Parameter	In	Type	Description
budget_id	path	string	The budget's id.
month	query	YYYY-MM	Keep this month only in every monthly_breakdown.

month only trims the monthly breakdowns: every amount, spent and committed still covers the whole budget.

Response

The budget object, plus:

Field	Type	Description
monthly_breakdown	array	The budget's plan per month: month (YYYY-MM) and amount. The sum of its top-level categories' plans.
categories	array	All its categories, as category objects.

Example

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

{
  "id": "7d2f9a40-3c8e-4b16-a5d7-2e9c0f81b4a3",
  "name": "Marketing 2026",
  "description": "Paid acquisition and events",
  "status": "active",
  "currency": "EUR",
  "total": "240000.00",
  "spent": "61250.40",
  "committed": "18000.00",
  "start_at": "2026-01-01T00:00:00Z",
  "end_at": "2026-12-31T00:00:00Z",
  "monthly_breakdown": [
    { "month": "2026-03", "amount": "20000.00" }
  ],
  "categories": [
    {
      "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-03", "amount": "8000.00" }
      ],
      "branch_spent": "24310.75",
      "branch_committed": "6000.00"
    },
    {
      "id": "5e8b1c73-a4f2-4d69-9c0e-7b3a2d1f8e46",
      "parent_id": "c41a8e5b-92d7-4f03-8b6e-1a7d3c5f9e20",
      "depth": 2,
      "name": "LinkedIn Ads",
      "amount": "48000.00",
      "spent": "24310.75",
      "committed": "6000.00",
      "monthly_breakdown": [
        { "month": "2026-03", "amount": "4000.00" }
      ],
      "branch_spent": "24310.75",
      "branch_committed": "6000.00"
    }
  ]
}

Errors

401, 403, 429 and 500, as in Errors and limits, and:

Status	code	When
400	invalid_parameter	month is not YYYY-MM.
404	not_found	No such budget, or it isn't shared with you.