Skip to main content

​
Endpoint

GET /api/v1/categories/budget-left
Calculate the remaining budget (budget left) for each category in a given month, including assigned amounts, rollover from previous months, and spent amounts.

​
Query parameters

​
month
string
Month for calculation in YYYY-MM format. Defaults to current month
​
as_of_date
string
Calculate spending as of this date (YYYY-MM-DD). Must be within the specified month. Defaults to last day of month
​
category_id
string
Filter results to a specific category UUID
​
group_id
string
Filter results to categories in this group UUID
​
goal_type
string
Filter by category goal type. Options: spending, savings, emergency_fund
​
only_overspent
boolean
default:"false"
Only return categories where budget_left is negative. Accepts true, false, 1, or 0
​
include_zero
boolean
default:"true"
Include categories with zero assigned, spent, and rollover. Accepts true, false, 1, or 0
​
min_budget_left
number
Filter categories with budget_left greater than or equal to this value
​
max_budget_left
number
Filter categories with budget_left less than or equal to this value
​
sort
string
Field to sort by. Options: budget_left, spent, assigned
​
order
string
default:"asc"
Sort order. Options: asc, desc
​
fields
string
Comma-separated list of fields to return. Available fields: category_id, category_name, group, goal, goal_type, month, assigned, rollover, spent, budget_left
​
limit
integer
default:"100"
Maximum number of results to return (1-1000)
​
offset
integer
default:"0"
Number of results to skip for pagination
​
cursor
string
Cursor for pagination. Cannot be used with offset

​
Response fields

​
data
array
Array of budget left calculation objects
​
category_id
string
Category UUID
​
category_name
string
Category name
​
group
string
Group name or “Uncategorized”
​
goal
number | null
Category budget goal
​
goal_type
string
Type of goal: spending, savings, or emergency_fund
​
month
string
Month for this calculation in YYYY-MM format
​
assigned
number
Amount assigned to this category for the month
​
rollover
number
Rollover amount from previous months (assigned - spent in prior months)
​
spent
number
Amount spent in this category during the month (up to as_of_date)
​
budget_left
number
Remaining budget calculated as: assigned + rollover - spent
​
meta
object
Pagination and metadata
​
total
integer
Total number of matching categories
​
returned
integer
Number of categories returned in this response
​
limit
integer
Maximum results per page
​
offset
integer
Current offset
​
next_cursor
string | null
Cursor for the next page, or null if no more results
​
month
string
Month used for calculation
​
start_date
string
First day of the month
​
end_date
string
Last day of the month
​
as_of_date
string
Date used for spending calculation
​
sort
string | null
Field used for sorting
​
order
string
Sort order applied

​
Example request

curl -X GET "https://api.cashcat.app/api/v1/categories/budget-left?month=2024-03&only_overspent=false&sort=budget_left&order=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example response

{
  "data": [
    {
      "category_id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "category_name": "Groceries",
      "group": "Essential Expenses",
      "goal": 600.00,
      "goal_type": "spending",
      "month": "2024-03",
      "assigned": 600.00,
      "rollover": 25.50,
      "spent": 545.30,
      "budget_left": 80.20
    },
    {
      "category_id": "d2e3f4a5-b6c7-8901-defg-234567890123",
      "category_name": "Dining Out",
      "group": "Essential Expenses",
      "goal": 200.00,
      "goal_type": "spending",
      "month": "2024-03",
      "assigned": 200.00,
      "rollover": 0.00,
      "spent": 215.75,
      "budget_left": -15.75
    },
    {
      "category_id": "e3f4a5b6-c7d8-9012-efgh-345678901234",
      "category_name": "Emergency Fund",
      "group": "Savings",
      "goal": 500.00,
      "goal_type": "emergency_fund",
      "month": "2024-03",
      "assigned": 500.00,
      "rollover": 1500.00,
      "spent": 0.00,
      "budget_left": 2000.00
    }
  ],
  "meta": {
    "total": 3,
    "returned": 3,
    "limit": 100,
    "offset": 0,
    "next_cursor": null,
    "month": "2024-03",
    "start_date": "2024-03-01",
    "end_date": "2024-03-31",
    "as_of_date": "2024-03-31",
    "sort": "budget_left",
    "order": "asc"
  }
}

​
Rollover calculation

The rollover amount is calculated by:
  1. Finding the earliest month with an assignment for the category
  2. For each month from that earliest month until the target month:
    • Add the assigned amount for that month
    • Subtract the spent amount for that month
  3. The cumulative difference becomes the rollover for the target month
This ensures that unspent budget from previous months carries forward when rollover is enabled for the category.

Build docs developers (and LLMs) love

Get started for freeTalk to us