Skip to main content
GET
/
api
/
budgets
curl -X GET "https://api.yourfinanceapp.com/api/budgets?month=1&year=2026" \
  -H "Authorization: Bearer YOUR_TOKEN"

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "categoryId": "660e8400-e29b-41d4-a716-446655440001",
    "categoryName": "Food & Dining",
    "categoryColor": "#FF6B6B",
    "categoryIcon": "Utensils",
    "amount": 50000,
    "spent": 42000,
    "directSpent": 30000,
    "remaining": 8000,
    "percentage": 84,
    "status": "WARNING",
    "children": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "categoryId": "660e8400-e29b-41d4-a716-446655440011",
        "categoryName": "Restaurants",
        "categoryColor": "#FF6B6B",
        "categoryIcon": "Restaurant",
        "amount": 20000,
        "spent": 12000,
        "directSpent": 12000,
        "remaining": 8000,
        "percentage": 60,
        "status": "OK",
        "children": []
      }
    ]
  },
  {
    "categoryId": "660e8400-e29b-41d4-a716-446655440002",
    "categoryName": "Uncategorized",
    "categoryColor": "#cccccc",
    "categoryIcon": "Wallet",
    "amount": 0,
    "spent": 5000,
    "directSpent": 5000,
    "remaining": 0,
    "percentage": 0,
    "status": "UNBUDGETED",
    "children": []
  }
]

​
Authentication

This endpoint requires JWT authentication via Bearer token.

​
Query Parameters

​
month
integer
Filter by month (1-12). Defaults to current month if not provided.
​
year
integer
Filter by year. Defaults to current year if not provided.

​
Response Structure

Returns a hierarchical tree of budget reports. Each node includes direct spending and recursive spending (including child categories).
​
id
string
Budget ID (if budget exists for this category)
​
categoryId
string
Category UUID
​
categoryName
string
Category name
​
categoryColor
string
Hex color code for the category
​
categoryIcon
string
Icon identifier for the category
​
amount
number
Budget limit amount (0 if no budget set)
​
spent
number
Total spent recursively (includes spending in child categories)
​
directSpent
number
Amount spent directly in this category (excludes children)
​
remaining
number
Remaining budget amount (max of 0 and amount - spent)
​
percentage
number
Percentage of budget spent (0-100+)
​
status
string
Budget status indicator:
  • OK: Less than 80% spent
  • WARNING: 80-99% spent
  • EXCEEDED: 100% or more spent
  • UNBUDGETED: No budget set for this category
​
children
array
Array of child budget reports with the same structure
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "categoryId": "660e8400-e29b-41d4-a716-446655440001",
    "categoryName": "Food & Dining",
    "categoryColor": "#FF6B6B",
    "categoryIcon": "Utensils",
    "amount": 50000,
    "spent": 42000,
    "directSpent": 30000,
    "remaining": 8000,
    "percentage": 84,
    "status": "WARNING",
    "children": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "categoryId": "660e8400-e29b-41d4-a716-446655440011",
        "categoryName": "Restaurants",
        "categoryColor": "#FF6B6B",
        "categoryIcon": "Restaurant",
        "amount": 20000,
        "spent": 12000,
        "directSpent": 12000,
        "remaining": 8000,
        "percentage": 60,
        "status": "OK",
        "children": []
      }
    ]
  },
  {
    "categoryId": "660e8400-e29b-41d4-a716-446655440002",
    "categoryName": "Uncategorized",
    "categoryColor": "#cccccc",
    "categoryIcon": "Wallet",
    "amount": 0,
    "spent": 5000,
    "directSpent": 5000,
    "remaining": 0,
    "percentage": 0,
    "status": "UNBUDGETED",
    "children": []
  }
]

curl -X GET "https://api.yourfinanceapp.com/api/budgets?month=1&year=2026" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Notes

  • All spending calculations respect the user’s timezone setting
  • The hierarchy reflects the category parent-child relationships
  • Categories without budgets are still included with status: "UNBUDGETED"
  • Recursive spending aggregation ensures parent categories show total spending across all children

Build docs developers (and LLMs) love

Get started for freeTalk to us