Skip to main content
GET
/
api
/
budgets
/
:id
/
status
// Get all budgets for current month
const response = await fetch(
  'https://api.yourfinanceapp.com/api/budgets',
  {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

const budgets = await response.json();

// Find specific budget by ID
const budgetId = '550e8400-e29b-41d4-a716-446655440000';
const budget = findBudgetById(budgets, budgetId);

function findBudgetById(budgets, id) {
  for (const budget of budgets) {
    if (budget.id === id) return budget;
    
    // Recursively search children
    const found = findBudgetById(budget.children, id);
    if (found) return found;
  }
  return null;
}

// Access status fields
console.log({
  spent: budget.spent,
  remaining: budget.remaining,
  status: budget.status,
  percentage: budget.percentage
});

{
  "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": []
}
This endpoint is derived from the list endpoint behavior. For individual budget status, use the list endpoint and filter the results client-side, or implement a dedicated status endpoint in your backend.

​
Alternative: Use List Endpoint

The /api/budgets list endpoint already provides comprehensive status information for all budgets, including:
  • Current spending (direct and recursive)
  • Remaining budget
  • Status indicators (OK, WARNING, EXCEEDED, UNBUDGETED)
  • Percentage used
To get status for a specific budget:
  1. Call GET /api/budgets?month=X&year=Y
  2. Find the budget by id in the response
  3. Extract the status fields

​
Status Indicators

​
status
string
Budget health indicator:
  • OK: Less than 80% of budget spent - spending is under control
  • WARNING: 80-99% of budget spent - approaching the limit
  • EXCEEDED: 100% or more spent - budget limit has been exceeded
  • UNBUDGETED: No budget set for this category

​
Status Calculation Logic

if (limit === 0) {
  status = 'UNBUDGETED';
} else {
  percentage = Math.round((spent / limit) * 100);
  
  if (percentage >= 100) {
    status = 'EXCEEDED';
  } else if (percentage >= 80) {
    status = 'WARNING';
  } else {
    status = 'OK';
  }
}

​
Example: Getting Budget Status

// Get all budgets for current month
const response = await fetch(
  'https://api.yourfinanceapp.com/api/budgets',
  {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

const budgets = await response.json();

// Find specific budget by ID
const budgetId = '550e8400-e29b-41d4-a716-446655440000';
const budget = findBudgetById(budgets, budgetId);

function findBudgetById(budgets, id) {
  for (const budget of budgets) {
    if (budget.id === id) return budget;
    
    // Recursively search children
    const found = findBudgetById(budget.children, id);
    if (found) return found;
  }
  return null;
}

// Access status fields
console.log({
  spent: budget.spent,
  remaining: budget.remaining,
  status: budget.status,
  percentage: budget.percentage
});

​
Status Response Fields

When you extract a budget from the list endpoint, you get:
​
spent
number
Total amount spent (includes child categories)
​
directSpent
number
Amount spent directly in this category only
​
remaining
number
Remaining budget (amount - spent, minimum 0)
​
percentage
number
Percentage of budget used (0-100+)
​
status
string
One of: OK, WARNING, EXCEEDED, UNBUDGETED
{
  "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": []
}

​
Implementation Recommendation

If you need a dedicated status endpoint, implement it in your backend: 
@Get(':id/status')
async getStatus(
  @Param('id') id: string,
  @CurrentUser('id') userId: string,
) {
  const budget = await this.budgetsService.findOneAndValidateOwner(id, userId);
  
  // Get current month spending
  const spent = await this.calculateSpending(budget);
  const remaining = Math.max(0, budget.amount - spent);
  const percentage = Math.round((spent / budget.amount) * 100);
  
  let status: string;
  if (percentage >= 100) status = 'EXCEEDED';
  else if (percentage >= 80) status = 'WARNING';
  else status = 'OK';
  
  return {
    budgetId: budget.id,
    amount: budget.amount,
    spent,
    remaining,
    percentage,
    status
  };
}

Build docs developers (and LLMs) love

Get started for freeTalk to us