# 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.

<!-- Generated from the OpenAPI spec by `php artisan api:docs`. Do not edit by hand. -->

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

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

#### Example response

```json
{
    "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

```bash
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

```json
{
    "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

```bash
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

```json
{
    "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

```bash
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

```json
{
    "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

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

#### Example response

```json
{
    "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

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

#### Example response

```json
{
    "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

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

#### Example response

```json
{
    "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`. |

---

Índice completo de la documentación: https://whisper.money/documentation.md?lang=es
