Whisper Money

Buscar en la documentación

Busca páginas y secciones.

Analytics

Figures rolled up from your transactions, balances and goals: cashflow, net worth, spending by category and by label, credit card usage and this month's savings, which cover your whole account rather than a space, with every amount in minor units of the currency given. Aggregates read your own transactions in a space instead, and give each currency its own bucket.

The example requests read your personal token from $WHISPER_MONEY_TOKEN: run export WHISPER_MONEY_TOKEN=wm_api_your_token_here before pasting them.

Retrieve the cashflow

GET /api/v1/analytics/cashflow

The cashflow of a date range: income, expenses, savings and investments against the previous period, your expenses split by the budgets that track them (fixed, variable and general), what your budgets still reserve, where the money came from and went by category, and the monthly trend. The range can touch at most 24 calendar months.

Scope: read. A personal token needs api:read; an OAuth token needs api:use.

Parameters

Name In Type Required Description
from query string (date) Yes The first day of the range, inclusive.
to query string (date) Yes The last day of the range, inclusive. Not before from.

Response

200

Field Type Description
data Cashflow
data.currency string The currency of every amount: your account's currency, as an ISO 4217 code.
data.summary object
data.summary.current CashflowPeriod The range's cashflow.
data.summary.current.income integer What came in: the transactions in income categories, and the uncategorized ones that brought money in.
data.summary.current.expense integer What went out: the transactions in expense categories, and the uncategorized ones that took money out. Savings, investments and transfers are not in it.
data.summary.current.net integer income minus expense.
data.summary.current.savings_rate number net as a percentage of income, rounded to one decimal and never above 100. 0 with no income.
data.summary.current.savings integer What was set aside into savings categories, net of withdrawals.
data.summary.current.investments integer What was set aside into investment categories, net of withdrawals.
data.summary.current.fixed_expense integer The part of expense tracked by budgets marked fixed (rent, subscriptions). Budgets are variable unless marked fixed, so 0 may only mean none has been marked yet. A transaction tracked by a fixed and a variable budget counts here, once.
data.summary.current.variable_expense integer The part of expense tracked by budgets marked variable (groceries, leisure). Catch-all budgets do not count.
data.summary.current.general_expense integer The rest of expense, which no budget tracks. The three parts add up to expense, and any can be negative in a period of refunds.
data.summary.current.reserved integer Current period only: what the budgets in budgets still hold back for spending, adding up their positive margins. An over-budget period adds nothing.
data.summary.current.budgets array of CashflowBudget Current period only: the budget periods in progress today that overlap the range. A range of up to 31 days counts weekly, bi-weekly and monthly budgets, one of up to 92 days those plus quarterly ones, and a longer one only yearly budgets.
data.summary.current.budgets[].budget_id string (uuid) The budget's id.
data.summary.current.budgets[].budget_period_id string (uuid) The id of the budget's period in progress.
data.summary.current.budgets[].name string The budget's name.
data.summary.current.budgets[].start_date string (date) The period's first day.
data.summary.current.budgets[].end_date string (date) The period's last day, included.
data.summary.current.budgets[].expense_type "fixed" | "variable" fixed or variable: which part of the expense split the budget's spending counts in.
data.summary.current.budgets[].allocated integer The period's limit, in minor units of currency.
data.summary.current.budgets[].spent integer What was spent against it so far.
data.summary.current.budgets[].margin integer allocated minus spent, negative once the period goes over its limit. Like the budgets endpoints, it leaves out any carried-over amount.
data.summary.previous CashflowPeriod The cashflow of the period before it, to compare with: the same number of days right before from, or the same number of whole months when the range is whole months. It has the expense split but no reserved or budgets, which are about today.
data.summary.previous.income integer What came in: the transactions in income categories, and the uncategorized ones that brought money in.
data.summary.previous.expense integer What went out: the transactions in expense categories, and the uncategorized ones that took money out. Savings, investments and transfers are not in it.
data.summary.previous.net integer income minus expense.
data.summary.previous.savings_rate number net as a percentage of income, rounded to one decimal and never above 100. 0 with no income.
data.summary.previous.savings integer What was set aside into savings categories, net of withdrawals.
data.summary.previous.investments integer What was set aside into investment categories, net of withdrawals.
data.summary.previous.fixed_expense integer The part of expense tracked by budgets marked fixed (rent, subscriptions). Budgets are variable unless marked fixed, so 0 may only mean none has been marked yet. A transaction tracked by a fixed and a variable budget counts here, once.
data.summary.previous.variable_expense integer The part of expense tracked by budgets marked variable (groceries, leisure). Catch-all budgets do not count.
data.summary.previous.general_expense integer The rest of expense, which no budget tracks. The three parts add up to expense, and any can be negative in a period of refunds.
data.summary.previous.reserved integer Current period only: what the budgets in budgets still hold back for spending, adding up their positive margins. An over-budget period adds nothing.
data.summary.previous.budgets array of CashflowBudget Current period only: the budget periods in progress today that overlap the range. A range of up to 31 days counts weekly, bi-weekly and monthly budgets, one of up to 92 days those plus quarterly ones, and a longer one only yearly budgets.
data.summary.previous.budgets[].budget_id string (uuid) The budget's id.
data.summary.previous.budgets[].budget_period_id string (uuid) The id of the budget's period in progress.
data.summary.previous.budgets[].name string The budget's name.
data.summary.previous.budgets[].start_date string (date) The period's first day.
data.summary.previous.budgets[].end_date string (date) The period's last day, included.
data.summary.previous.budgets[].expense_type "fixed" | "variable" fixed or variable: which part of the expense split the budget's spending counts in.
data.summary.previous.budgets[].allocated integer The period's limit, in minor units of currency.
data.summary.previous.budgets[].spent integer What was spent against it so far.
data.summary.previous.budgets[].margin integer allocated minus spent, negative once the period goes over its limit. Like the budgets endpoints, it leaves out any carried-over amount.
data.sankey object
data.sankey.income_categories array of CategoryAmount Where the money came from, by top-level category. A category is netted and lands on the side its net points at, so an expense category that got more back than it spent is listed here as a refund. Savings and investment withdrawals and transfers set to count as an inflow appear here too, and the uncategorized money that came in is one row with no category_id.
data.sankey.income_categories[].category_id string (uuid) or null The category's id, or null for the row that gathers the transactions with no category.
data.sankey.income_categories[].name string or null The category's name. The row with no category is Unknown Income or Unknown Expense. On the cashflow's top level, a category whose net crossed to the other side says so: Groceries (refund), Savings (withdrawal), Salary (reversal).
data.sankey.income_categories[].type string or null The category's type: income, expense, savings, investment or transfer.
data.sankey.income_categories[].color string or null The category's colour in the app.
data.sankey.income_categories[].icon string or null The category's icon in the app, a Lucide icon name.
data.sankey.income_categories[].amount integer What the category adds up to over the period, as a positive amount in minor units of currency.
data.sankey.income_categories[].has_children boolean Whether the category has subcategories to drill into.
data.sankey.income_categories[].is_direct boolean When drilling into a category, true on the row for the transactions booked to that category itself rather than to one of its children.
data.sankey.expense_categories array of CategoryAmount Where the money went, by top-level category, built the same way. Savings, investments and transfers set to count as an outflow appear here too.
data.sankey.expense_categories[].category_id string (uuid) or null The category's id, or null for the row that gathers the transactions with no category.
data.sankey.expense_categories[].name string or null The category's name. The row with no category is Unknown Income or Unknown Expense. On the cashflow's top level, a category whose net crossed to the other side says so: Groceries (refund), Savings (withdrawal), Salary (reversal).
data.sankey.expense_categories[].type string or null The category's type: income, expense, savings, investment or transfer.
data.sankey.expense_categories[].color string or null The category's colour in the app.
data.sankey.expense_categories[].icon string or null The category's icon in the app, a Lucide icon name.
data.sankey.expense_categories[].amount integer What the category adds up to over the period, as a positive amount in minor units of currency.
data.sankey.expense_categories[].has_children boolean Whether the category has subcategories to drill into.
data.sankey.expense_categories[].is_direct boolean When drilling into a category, true on the row for the transactions booked to that category itself rather than to one of its children.
data.sankey.total_income integer What income_categories adds up to.
data.sankey.total_expense integer What expense_categories adds up to. Savings, investments and outflow transfers are in it, so it is not summary.current.expense.
data.trend array of object Income, expense and net per calendar month the range touches, oldest first. Counted like current: savings, investments and transfers left out.
data.trend[].month string
data.trend[].income integer
data.trend[].expense integer
data.trend[].net integer

Example request

curl "https://whisper.money/api/v1/analytics/cashflow?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $WHISPER_MONEY_TOKEN"

Example response

{
    "data": {
        "currency": "EUR",
        "summary": {
            "current": {
                "income": 260000,
                "expense": 96122,
                "net": 163878,
                "savings_rate": 63,
                "savings": 10000,
                "investments": 0,
                "fixed_expense": 90000,
                "variable_expense": 5345,
                "general_expense": 777,
                "reserved": 17950,
                "budgets": [
                    {
                        "budget_id": "0199a3f8-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
                        "budget_period_id": "0199a3fa-1b2c-7d3e-8f4a-5b6c7d8e9f01",
                        "name": "Groceries",
                        "start_date": "2026-10-01",
                        "end_date": "2026-10-31",
                        "expense_type": "variable",
                        "allocated": 50000,
                        "spent": 32050,
                        "margin": 17950
                    }
                ]
            },
            "previous": {
                "income": 260000,
                "expense": 96122,
                "net": 163878,
                "savings_rate": 63,
                "savings": 10000,
                "investments": 0,
                "fixed_expense": 90000,
                "variable_expense": 5345,
                "general_expense": 777,
                "reserved": 17950,
                "budgets": [
                    {
                        "budget_id": "0199a3f8-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
                        "budget_period_id": "0199a3fa-1b2c-7d3e-8f4a-5b6c7d8e9f01",
                        "name": "Groceries",
                        "start_date": "2026-10-01",
                        "end_date": "2026-10-31",
                        "expense_type": "variable",
                        "allocated": 50000,
                        "spent": 32050,
                        "margin": 17950
                    }
                ]
            }
        },
        "sankey": {
            "income_categories": [
                {
                    "category_id": "0199a3f5-2b3c-7d4e-8f5a-6b7c8d9e0f12",
                    "name": "Groceries",
                    "type": "expense",
                    "color": "orange",
                    "icon": "ShoppingCart",
                    "amount": 15345,
                    "has_children": false,
                    "is_direct": false
                }
            ],
            "expense_categories": [
                {
                    "category_id": "0199a3f5-2b3c-7d4e-8f5a-6b7c8d9e0f12",
                    "name": "Groceries",
                    "type": "expense",
                    "color": "orange",
                    "icon": "ShoppingCart",
                    "amount": 15345,
                    "has_children": false,
                    "is_direct": false
                }
            ],
            "total_income": 260000,
            "total_expense": 106122
        },
        "trend": [
            {
                "month": "2026-10",
                "income": 260000,
                "expense": 96122,
                "net": 163878
            }
        ]
    }
}

Errors

Status When
401 No bearer token, or one that is unknown, expired or revoked.
403 The token lacks the scope (insufficient_scope), the account has no Standard plan (plan_required, with a subscribe_url) or it is a shared demo account (shared_account).
422 Validation error
429 The rate limit is exhausted. Wait the seconds in Retry-After.

Retrieve the net worth

GET /api/v1/analytics/net-worth

Your net worth at the end of a date range against the end of the previous period, and every account's balance over the range, monthly or daily. A monthly range can touch at most 120 calendar months, a daily one cover at most 366 days.

Scope: read. A personal token needs api:read; an OAuth token needs api:use.

Parameters

Name In Type Required Description
from query string (date) Yes The first day of the range, inclusive.
to query string (date) Yes The last day of the range, inclusive. Not before from.
granularity query "monthly" | "daily" No monthly (the default) for a point at the end of each month of the range, daily for one per day.

Response

200

Field Type Description
data NetWorth
data.currency string The currency of every amount: your account's currency, as an ISO 4217 code. Balances in another currency are converted at each day's exchange rate.
data.granularity "monthly" | "daily" monthly or daily, as requested.
data.net_worth integer Your net worth on to: the balances of the accounts with counts_in_net_worth, converted to currency, a loan's debt counting against it. Credit cards are never part of it, and loans and real estate only when your net worth settings include them.
data.previous_net_worth integer Your net worth at the end of the previous period: the same number of days right before from, or the same number of whole months when the range is whole months.
data.accounts array of object Every account the evolution covers, archived ones and the ones left out of net_worth included: its id, name, type, own currency, and whether it is part of net_worth.
data.accounts[].id string
data.accounts[].name string
data.accounts[].type string
data.accounts[].currency string
data.accounts[].counts_in_net_worth boolean
data.evolution array of NetWorthPoint One point per month the range touches, at the month's last day even when to falls before it, or one per day of the range; oldest first, with each account's balance on it.
data.evolution[].period string The month (2026-10) or, with daily granularity, the day (2026-10-15).
data.evolution[].balances array of object One entry per account in accounts, in the same order: balance in currency, a loan's as the positive amount owed; original_balance and original_currency the account's own figure when its currency is another one, null otherwise; invested_amount what was put into an investment or retirement account on a monthly point, null for other types, on daily points or when not recorded.
data.evolution[].balances[].account_id string
data.evolution[].balances[].balance integer
data.evolution[].balances[].original_balance integer or null
data.evolution[].balances[].original_currency string or null
data.evolution[].balances[].invested_amount integer or null

Example request

curl "https://whisper.money/api/v1/analytics/net-worth?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $WHISPER_MONEY_TOKEN"

Example response

{
    "data": {
        "currency": "EUR",
        "granularity": "monthly",
        "net_worth": 366364,
        "previous_net_worth": 360000,
        "accounts": [
            {
                "id": "0199a3f2-8b1c-7d4e-9f5a-1b2c3d4e5f60",
                "name": "Main checking",
                "type": "checking",
                "currency": "EUR",
                "counts_in_net_worth": true
            }
        ],
        "evolution": [
            {
                "period": "2026-10",
                "balances": [
                    {
                        "account_id": "0199a3f2-8b1c-7d4e-9f5a-1b2c3d4e5f60",
                        "balance": 130000,
                        "original_balance": null,
                        "original_currency": null,
                        "invested_amount": null
                    }
                ]
            }
        ]
    }
}

Errors

Status When
401 No bearer token, or one that is unknown, expired or revoked.
403 The token lacks the scope (insufficient_scope), the account has no Standard plan (plan_required, with a subscribe_url) or it is a shared demo account (shared_account).
422 Validation error
429 The rate limit is exhausted. Wait the seconds in Retry-After.

Retrieve spending by category

GET /api/v1/analytics/spending-by-category

Your expenses in a date range by top-level category, each with its subcategories rolled into it. Pass parent_category_id to drill into a category: its children come back instead, plus a row for what was booked to the category itself (is_direct). The range can touch at most 120 calendar months.

Scope: read. A personal token needs api:read; an OAuth token needs api:use.

Parameters

Name In Type Required Description
from query string (date) Yes The first day of the range, inclusive.
to query string (date) Yes The last day of the range, inclusive. Not before from.
parent_category_id query string (uuid) or null No Drill into one of your categories: its children are returned instead of the top-level categories.

Response

200

Field Type Description
data SpendingByCategory
data.currency string The currency of every amount: your account's currency, as an ISO 4217 code.
data.total integer What categories adds up to.
data.categories array of CategoryAmount The expense categories with spending in the range, largest first, each with its subcategories rolled into it. Only the ones whose spending is above zero: a category that refunds took below zero is left out, and so are uncategorized transactions, so total can be above the cashflow's expense for the same range.
data.categories[].category_id string (uuid) or null The category's id, or null for the row that gathers the transactions with no category.
data.categories[].name string or null The category's name. The row with no category is Unknown Income or Unknown Expense. On the cashflow's top level, a category whose net crossed to the other side says so: Groceries (refund), Savings (withdrawal), Salary (reversal).
data.categories[].type string or null The category's type: income, expense, savings, investment or transfer.
data.categories[].color string or null The category's colour in the app.
data.categories[].icon string or null The category's icon in the app, a Lucide icon name.
data.categories[].amount integer What the category adds up to over the period, as a positive amount in minor units of currency.
data.categories[].has_children boolean Whether the category has subcategories to drill into.
data.categories[].is_direct boolean When drilling into a category, true on the row for the transactions booked to that category itself rather than to one of its children.

Example request

curl "https://whisper.money/api/v1/analytics/spending-by-category?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $WHISPER_MONEY_TOKEN"

Example response

{
    "data": {
        "currency": "EUR",
        "total": 105345,
        "categories": [
            {
                "category_id": "0199a3f5-2b3c-7d4e-8f5a-6b7c8d9e0f12",
                "name": "Groceries",
                "type": "expense",
                "color": "orange",
                "icon": "ShoppingCart",
                "amount": 15345,
                "has_children": false,
                "is_direct": false
            }
        ]
    }
}

Errors

Status When
401 No bearer token, or one that is unknown, expired or revoked.
403 The token lacks the scope (insufficient_scope), the account has no Standard plan (plan_required, with a subscribe_url) or it is a shared demo account (shared_account).
422 Validation error
429 The rate limit is exhausted. Wait the seconds in Retry-After.

Retrieve spending by label

GET /api/v1/analytics/spending-by-label

Your expenses in a date range by label, largest first, each against the previous period. A transaction counts under every label it carries. The labels of savings goals are left out: they track contributions, not spending. The range can touch at most 120 calendar months.

Scope: read. A personal token needs api:read; an OAuth token needs api:use.

Parameters

Name In Type Required Description
from query string (date) Yes The first day of the range, inclusive.
to query string (date) Yes The last day of the range, inclusive. Not before from.

Response

200

Field Type Description
data SpendingByLabel
data.currency string The currency of every amount: your account's currency, as an ISO 4217 code.
data.total integer What labels adds up to. A transaction counts under every label it carries, so this can be above what you spent in the range.
data.previous_from string (date) The first day of the previous period previous_amount reads: the same number of days right before from, or the same number of whole months when the range is whole months.
data.previous_to string (date) The last day of the previous period.
data.labels array of LabelAmount The labels with spending in the range, largest first. Only the ones whose spending is above zero, and never the label of a savings goal, which tracks contributions rather than spending.
data.labels[].label_id string (uuid) The label's id.
data.labels[].name string The label's name.
data.labels[].color string The label's colour in the app.
data.labels[].amount integer What was spent under the label over the range, as a positive amount in minor units of currency.
data.labels[].previous_amount integer What was spent under the label over the previous period, 0 when nothing was.

Example request

curl "https://whisper.money/api/v1/analytics/spending-by-label?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $WHISPER_MONEY_TOKEN"

Example response

{
    "data": {
        "currency": "EUR",
        "total": 79250,
        "previous_from": "2026-09-01",
        "previous_to": "2026-09-30",
        "labels": [
            {
                "label_id": "0199a3f6-3c4d-7e5f-9a6b-7c8d9e0f1a23",
                "name": "Holidays",
                "color": "blue",
                "amount": 48250,
                "previous_amount": 31000
            }
        ]
    }
}

Errors

Status When
401 No bearer token, or one that is unknown, expired or revoked.
403 The token lacks the scope (insufficient_scope), the account has no Standard plan (plan_required, with a subscribe_url) or it is a shared demo account (shared_account).
422 Validation error
429 The rate limit is exhausted. Wait the seconds in Retry-After.

Retrieve credit card usage

GET /api/v1/analytics/credit-card-usage

How much of each of your credit cards is in use, archived cards left out: what is still to be charged, what is left of the limit and how that built up day by day. Each card's amounts are in its own currency.

Scope: read. A personal token needs api:read; an OAuth token needs api:use.

Response

200

Field Type Description
data array of CreditCardUsage
data[].account_id string (uuid) The credit card's account id.
data[].name string The account's name.
data[].currency string The currency of the card's amounts: the account's own currency, as an ISO 4217 code.
data[].limit integer or null The card's credit limit in minor units, or null while none is set.
data[].used integer What is still to be charged between period_from and today, less the payments made on those statements, never below 0.
data[].available integer or null limit minus used, negative over the limit; null while no limit is set.
data[].period_from string (date) The first day used covers: the start of the statement paid next, or of the calendar month while the card has no statement dates.
data[].period_to string (date) The last day of the window: the open statement's closing date, or the end of the calendar month.
data[].daily array of object used as it stood at the end of each day from period_from through today, oldest first: the line the app draws on the card.
data[].daily[].date string
data[].daily[].used integer

Example request

curl https://whisper.money/api/v1/analytics/credit-card-usage \
  -H "Authorization: Bearer $WHISPER_MONEY_TOKEN"

Example response

{
    "data": [
        {
            "account_id": "0199a3f3-7d2e-7c5f-8b9a-3e6d2c4b5a71",
            "name": "Visa Gold",
            "currency": "EUR",
            "limit": 300000,
            "used": 124000,
            "available": 176000,
            "period_from": "2026-10-06",
            "period_to": "2026-11-05",
            "daily": [
                {
                    "date": "2026-10-06",
                    "used": 0
                },
                {
                    "date": "2026-10-07",
                    "used": 4500
                }
            ]
        }
    ]
}

Errors

Status When
401 No bearer token, or one that is unknown, expired or revoked.
403 The token lacks the scope (insufficient_scope), the account has no Standard plan (plan_required, with a subscribe_url) or it is a shared demo account (shared_account).
429 The rate limit is exhausted. Wait the seconds in Retry-After.

Retrieve this month's savings

GET /api/v1/analytics/monthly-savings

The month in progress across your monthly savings goals that are not archived: what they saved so far against their targets, each goal's month, and how every monthly goal did last month.

Scope: read. A personal token needs api:read; an OAuth token needs api:use.

Response

200

Field Type Description
data MonthlySavings
data.currency string The currency of every amount: your account's currency, as an ISO 4217 code.
data.month string The month in progress on your own clock, as YYYY-MM.
data.saved integer What the running goals saved so far this month. A goal whose first month is partial (created in the month's last 5 days) is left out of saved and target.
data.target integer What the running goals aim to save this month, each against its own target.
data.days_left integer The days left in the month, today included.
data.goals array of object Every monthly goal that is not archived, oldest first, with its month in progress as GET /api/v1/savings-goals gives it under monthly.current (null when the month has not opened for it yet). A goal whose month is partial is listed with what it saved but is not in saved and target. Goals of every space you are in count, but only yours.
data.goals[].id string
data.goals[].name string
data.goals[].current object or null
data.goals[].current.month string
data.goals[].current.target integer
data.goals[].current.saved integer
data.goals[].current.difference integer
data.goals[].current.status string
data.goals[].current.income_base integer or null
data.goals[].current.remaining integer
data.goals[].current.days_left integer
data.last_month object or null How your monthly goals did last month, archived ones included: how many met their target of how many were judged. null when no goal was judged that month.
data.last_month.month string
data.last_month.met integer
data.last_month.total integer

Example request

curl https://whisper.money/api/v1/analytics/monthly-savings \
  -H "Authorization: Bearer $WHISPER_MONEY_TOKEN"

Example response

{
    "data": {
        "currency": "EUR",
        "month": "2026-10",
        "saved": 25000,
        "target": 30000,
        "days_left": 17,
        "goals": [
            {
                "id": "0199a3fb-2c3d-7e4f-8a5b-6c7d8e9f0a12",
                "name": "Emergency fund",
                "current": {
                    "month": "2026-10",
                    "target": 30000,
                    "saved": 25000,
                    "difference": -5000,
                    "status": "in_progress",
                    "income_base": null,
                    "remaining": 5000,
                    "days_left": 17
                }
            }
        ],
        "last_month": {
            "month": "2026-09",
            "met": 1,
            "total": 2
        }
    }
}

Errors

Status When
401 No bearer token, or one that is unknown, expired or revoked.
403 The token lacks the scope (insufficient_scope), the account has no Standard plan (plan_required, with a subscribe_url) or it is a shared demo account (shared_account).
429 The rate limit is exhausted. Wait the seconds in Retry-After.

Aggregate transactions

GET /api/v1/analytics/aggregate

Your transactions in a space over a date range, grouped by up to two dimensions and added up: their sum, count, average, smallest and largest amount. As in the app, another member's transactions are left out. Each bucket is also split by currency, so amounts in different currencies are never added together, and every amount is your share of the account, in minor units of the bucket's currency. A transaction booked on an archived account stops counting from the day it was archived. Every type of transaction counts unless types narrows it: pass types=expense for spending, since transfers, savings and investments otherwise add in too. Grouped by a period, every period of the range comes back, with zeros where nothing was booked. A response holds at most 1000 buckets: one that would hold more is a 422 under group_by.

Scope: read. A personal token needs api:read; an OAuth token needs api:use.

Parameters

Name In Type Required Description
group_by[] query "day" | "week" | "month" | "year" | "category" | "label" | "account" | "type" No Up to two dimensions to group by, at most one of them a period (day, week, month or year). A week is named by its Monday. Without it, the transactions are added up per currency only. Also takes a comma-separated list: group_by=month,category.
metrics[] query "sum" | "count" | "avg" | "min" | "max" No What to work out over the amounts of each bucket. Defaults to sum and count.
from query string (date) Yes The earliest transaction date, inclusive.
to query string (date) Yes The latest transaction date, inclusive. Not before from.
category_ids[] query array of string (uuid) No Only the transactions in any of these categories.
include_subcategories query boolean No Whether category_ids also matches their subcategories. Defaults to true.
label_ids[] query array of string (uuid) No Only the transactions tagged with any of these labels. Grouped by label, only these labels are listed.
account_ids[] query array of string (uuid) No Only the transactions of any of these accounts.
types[] query array of CategoryType No Only the transactions of these types: income, expense, transfer, savings or investment. A transaction's type is its category's, and an uncategorized one is expense when it took money out and income otherwise.
query query string No Free text matched against the description and the creditor and debtor names.
space query string (uuid) No The id of the space to work in (see GET /spaces). Defaults to your personal space. On writes it may also be sent in the JSON body.

Response

200

Field Type Description
data TransactionAggregate
data.group_by array of string The dimensions the buckets are grouped by, in the order asked for.
data.metrics array of string The metrics every bucket carries.
data.from string (date) The first day of the range.
data.to string (date) The last day of the range.
data.buckets array of AggregateBucket The groups, oldest period first and then by name. Grouped by a period, every period of the range is listed for every combination of the other dimension and currency, with sum and count at 0 where nothing was booked.
data.buckets[].day string (date) The day, when grouped by day.
data.buckets[].week string (date) The Monday the week starts on, when grouped by week. The first week can start before from.
data.buckets[].month string The month, as YYYY-MM, when grouped by month.
data.buckets[].year string The year, when grouped by year.
data.buckets[].category_id string (uuid) or null The category's id, when grouped by category. null gathers the transactions with no category.
data.buckets[].category_name string or null The category's name, when grouped by category.
data.buckets[].label_id string (uuid) or null The label's id, when grouped by label. null gathers the transactions with no label. A transaction with several labels counts once in each of them.
data.buckets[].label_name string or null The label's name, when grouped by label.
data.buckets[].account_id string (uuid) The account's id, when grouped by account.
data.buckets[].account_name string The account's name, when grouped by account.
data.buckets[].type string The transactions' type, when grouped by type: income, expense, transfer, savings or investment.
data.buckets[].currency string The currency of the bucket's amounts, as an ISO 4217 code. Amounts in different currencies are never added together: each currency gets its own bucket.
data.buckets[].sum integer What the amounts add up to, signed, in minor units of currency: negative for money out. Only when asked for in metrics.
data.buckets[].count integer How many transactions the bucket holds. Only when asked for in metrics.
data.buckets[].avg integer or null The average amount, rounded to a whole minor unit, or null for an empty bucket. Only when asked for in metrics.
data.buckets[].min integer or null The smallest (most negative) amount, or null for an empty bucket. Only when asked for in metrics.
data.buckets[].max integer or null The largest amount, or null for an empty bucket. Only when asked for in metrics.

Example request

curl "https://whisper.money/api/v1/analytics/aggregate?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $WHISPER_MONEY_TOKEN"

Example response

{
    "data": {
        "group_by": [
            "month",
            "category"
        ],
        "metrics": [
            "sum",
            "count"
        ],
        "from": "2026-10-01",
        "to": "2026-10-31",
        "buckets": [
            {
                "day": "2026-10-04",
                "week": "2026-09-28",
                "month": "2026-10",
                "year": "2026",
                "category_id": "0199a3f5-2b3c-7d4e-8f5a-6b7c8d9e0f12",
                "category_name": "Groceries",
                "label_id": "0199a3f5-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
                "label_name": "Holidays",
                "account_id": "0199a3f5-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
                "account_name": "Main account",
                "type": "expense",
                "currency": "EUR",
                "sum": -15345,
                "count": 12,
                "avg": -1279,
                "min": -4500,
                "max": -250
            }
        ]
    }
}

Errors

Status When
401 No bearer token, or one that is unknown, expired or revoked.
403 The token lacks the scope (insufficient_scope), the account has no Standard plan (plan_required, with a subscribe_url) or it is a shared demo account (shared_account).
422 The request failed validation.
429 The rate limit is exhausted. Wait the seconds in Retry-After.