Penny Docs
Spending

Get Spending By Period

GET
/v1/households/{household_id}/analytics/spending-by-period

Groups income and expenses into daily, monthly, quarterly, or yearly periods over an inclusive date range. Each period includes totals, counts, and category breakdowns in the household's reporting currency; periods with no activity are returned with zero totals.

Category totals determine the income or expense side and retain their signs. Hidden and deleted transactions, transactions on deleted accounts, split parents, and transfers are excluded; pending transactions are included. Only transactions within the requested dates contribute, even for partial calendar periods.

Authorization

PersonalApiToken
AuthorizationBearer <token>

Use your personal API token (penny_pat_…) as the bearer credential. Enter the token only; the client adds the Bearer prefix. Read-only tokens permit read requests. Read/write tokens remain limited by your current household membership and role. See https://penny.finance/docs/api#authentication for setup.

In: header

Path Parameters

household_id*Household Id

Query Parameters

start_date*Start Date
Formatdate
end_date*End Date
Formatdate
merchant_ids?array<string>|null
tag_ids?array<string>|null
category_ids?array<string>|null
category_group_ids?array<string>|null
account_ids?array<string>|null
uncategorized?boolean|null
unknown_merchant?boolean|null
need_review?boolean|null
min_amount?|

Interpreted in the household's currency. Transaction amounts in other currencies are converted before the filter is applied. Amounts and thresholds are rounded to the currency minor unit using half-even rounding for comparison.

max_amount?|

Interpreted in the household's currency. Transaction amounts in other currencies are converted before the filter is applied. Amounts and thresholds are rounded to the currency minor unit using half-even rounding for comparison.

time_segment*TimeSegment

Value in

  • "daily"
  • "monthly"
  • "quarterly"
  • "yearly"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/households/string/analytics/spending-by-period?start_date=2019-08-24&end_date=2019-08-24&time_segment=daily"
{  "periods": [    {      "period": "2026-08",      "income": {        "total": {          "amount": "68.42",          "currency": "USD"        },        "count": 42,        "category_breakdown": [          {            "category_id": "Ct5nR8wY1jFu",            "category_name": "Coffee & Dining",            "total": {              "amount": "68.42",              "currency": "USD"            },            "count": 18,            "emoji": "☕️"          }        ]      },      "expenses": {        "total": {          "amount": "68.42",          "currency": "USD"        },        "count": 42,        "category_breakdown": [          {            "category_id": "Ct5nR8wY1jFu",            "category_name": "Coffee & Dining",            "total": {              "amount": "68.42",              "currency": "USD"            },            "count": 18,            "emoji": "☕️"          }        ]      }    }  ]}

Get Accumulated Spending GET

Summarizes income and expenses over an inclusive date range, with transaction counts and category breakdowns. Amounts and amount filters use the household's…

Get Cashflow By Period GET

Returns income, expenses, and net cashflow for each calendar period intersecting an inclusive date range, optionally filtered by accounts or tags. Amounts…