The Dashboard endpoint provides a comprehensive snapshot of the authenticated user’s financial health in a single request. It aggregates data across Accounts, Transactions, Budgets, Debts, Loans, and Pensions at query time — there is no dedicated Dashboard data model or persistent state. All calculations are performed synchronously against the SQLite database and returned as a single JSON object.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/soker90/finper/llms.txt
Use this file to discover all available pages before exploring further.
The dashboard has no own data model. It aggregates live data from the
accounts, transactions, budgets, debts, loans, and pensions tables. All monetary values in the response are rounded to two decimal places via the roundMoney utility from @soker90/finper-db.GET /api/dashboard/stats
Retrieve the full aggregated financial overview for the authenticated user.GET /api/dashboard/stats — requires token header.
Response — 200 OK
Returns a singleDashboardStatsResult object.
Net Worth & Balance
Sum of all active account balances.
Total outstanding debt amount owed by the user (from the Debts module).
Total pending principal remaining across all active loans.
Calculated as
totalBalance - totalDebts - totalLoansPending + totalReceivable.Current Month
Total income transactions for the current calendar month.
Total expense transactions for the current calendar month.
Current month savings rate as a percentage:
((income - expenses) / income) * 100. Returns 0 if income is zero.Month-over-Month Trend
Comparison of the current month vs the previous month.
income.current— current month incomeincome.previous— previous month incomeexpenses.current— current month expensesexpenses.previous— previous month expenses
Historical Summary
Array of monthly summary objects for the last 6 calendar months. Each object contains month/year, total income, and total expenses — useful for rendering bar or line charts.
Expense Velocity
Cumulative daily expense arrays for the current and previous months.
currentMonth— array of{ day: number, amount: number }(cumulative through each day of the current month)previousMonth— same structure for the previous month
Average daily expense for the current month to date (
monthlyExpenses / dayOfMonth).Projected total expense for the full current month based on
dailyAvgExpense * daysInMonth.Estimated number of months the current balance would last at the filtered average monthly expense rate (last 3 months, excluding outlier months).
Rankings
Top expense categories for the current month, sorted by amount descending. Each entry:
{ name: string, amount: number, parentName?: string }.Top stores by expense amount for the current month. Each entry:
{ name: string, amount: number }.Budget Compliance
Percentage indicating how well the user is adhering to their current-month budgets. Computed from actual expenses vs total budgeted amount.
Pension
Pension summary if pension data exists;
null otherwise.employeeAmount— total employee contributionscompanyAmount— total employer contributionstotal— current total pension valuetransactions— array of serialized pension snapshot records
Pension return as a percentage:
((total - contributed) / contributed) * 100. Returns 0 if no contributions exist.Health Score
A composite financial health score (0–100) and its component sub-scores.
total— overall health scoresavingsRate— sub-score derived from historical savings ratedebtRatio— sub-score from total debt vs total balance ratiobudgetAdherence— sub-score from budget compliancecashRunway— sub-score from cash runway monthspensionReturn— sub-score from pension performance
Insights
Array of dynamically generated insight objects. Each insight surfaces an actionable observation (e.g. a category approaching its budget limit, an unusual spike in spending). The structure of each insight is
{ type: string, message: string, ... }.