Analytics API - Budgetron

The Analytics API provides endpoints for generating financial reports, spending analysis, and dashboard summaries.

getDashboardSummary

Get a comprehensive dashboard summary including cash flow and overview statistics.

await client.analytics.getDashboardSummary()

Parameters

No parameters required. Automatically uses the last 6 months for cash flow analysis.

Response

object

Cash flow report for the last 6 months

object

Overview statistics including income, expenses, savings, and investments

See getCashFlowReport and the Overview Summary section below for detailed response structures.

getCashFlowReport

Generate a cash flow report for a specific time range.

await client.analytics.getCashFlowReport({
  range: "last_6_months"
})

Parameters

enum

required

Time range for the report:

this_month: Current month
last_3_months: Last 3 months
last_6_months: Last 6 months
ytd: Year to date
1_year: Last 12 months
all: All time

Response

string

Base currency code for the report

string[]

Array of currency codes that were converted to base currency

object

Attribution for currency exchange rate provider

text: Attribution text
url: Attribution URL

object

Summary statistics for the period

Summary object includes:

string

Total income for the period

string

Total expenses for the period

string

Total transfers for the period

string

Net surplus (income - expenses)

string

Average monthly income

string

Average monthly expenses

string

Average monthly surplus

array

Array of cash flow data points by period

Each data point includes:

string

Period identifier (e.g., “2024-03”, “2024-Q1”)

string

Income for the period

string

Expenses for the period

string

Transfers for the period

string

Surplus for the period

string[]

Currencies converted in this period

object

Metadata about the report

Metadata includes:

string

The range parameter used

Date

Report start date

Date

Report end date

enum

Data granularity: day, week, month, or quarter

getCategorySpend

Get spending breakdown by category for a date range.

await client.analytics.getCategorySpend({
  from: new Date("2024-01-01"),
  to: new Date("2024-03-31"),
  limit: 10
})

Parameters

Date

required

Start date for the analysis

Date

required

End date for the analysis

number

required

Maximum number of categories to return (minimum: 1)

Response

string

Base currency code

string[]

Array of converted currency codes

object

Currency exchange attribution information

array

Array of category spending data

Each category data object includes:

string

Category ID

string

Category name

string

Category icon

string

Category type (EXPENSE)

string | null

Parent category ID if applicable

string | null

Parent category name

string | null

Parent category icon

object

Total spending for this category

Total object includes:

string

Total in base currency

array

Array of amounts by original currency

Each currency amount includes:

currency: Currency code
amount: Original amount
convertedAmount: Amount converted to base currency

getCategoryIncome

Get income breakdown by category for a date range.

await client.analytics.getCategoryIncome({
  from: new Date("2024-01-01"),
  to: new Date("2024-03-31"),
  limit: 10
})

Parameters

Same as getCategorySpend.

Response

Same structure as getCategorySpend, but for income categories (type: INCOME).

Overview Summary

The overview summary (part of getDashboardSummary) includes the following cash flow types:

INCOME: Total income
EXPENSE: Total expenses
SAVINGS: Savings transactions
INVESTMENT: Investment transactions

For each cash flow type, the following periods are included:

object

Year-to-date totals

object

Current month totals

object

Last month totals

object

6-month average

Each period object includes:

baseCurrency: Amount in base currency
byCurrency: Array of amounts by currency with original and converted values

TypeScript Types

type CashFlowReportRange = 
  | "this_month"
  | "last_3_months"
  | "last_6_months"
  | "ytd"
  | "1_year"
  | "all"

type CashFlowReportGranularity = "day" | "week" | "month" | "quarter"

type CashFlowReport = {
  baseCurrency: CurrencyCode
  convertedCurrencies: CurrencyCode[]
  currencyExchangeAttribution?: {
    text: string
    url: string
  }
  summary: {
    income: Intl.StringNumericLiteral
    expense: Intl.StringNumericLiteral
    transfer: Intl.StringNumericLiteral
    surplus: Intl.StringNumericLiteral
    monthlyAverageIncome: Intl.StringNumericLiteral
    monthlyAverageExpense: Intl.StringNumericLiteral
    monthlyAverageSurplus: Intl.StringNumericLiteral
  }
  data: CashFlowReportData[]
  meta: {
    range: CashFlowReportRange
    startDate: Date
    endDate: Date
    granularity: CashFlowReportGranularity
  }
}

type CategoryReport = {
  baseCurrency: CurrencyCode
  convertedCurrencies: CurrencyCode[]
  currencyExchangeAttribution?: {
    text: string
    url: string
  }
  data: CategoryReportData[]
}

​getDashboardSummary

​Parameters

​Response

​getCashFlowReport

​Parameters

​Response

​getCategorySpend

​Parameters

​Response

​getCategoryIncome

​Parameters

​Response

​Overview Summary

​TypeScript Types

getDashboardSummary

Parameters

Response

getCashFlowReport

Parameters

Response

getCategorySpend

Parameters

Response

getCategoryIncome

Parameters

Response

Overview Summary

TypeScript Types