Penny Docs
Spending

Get Category Breakdown

GET
/v1/households/{household_id}/analytics/category-breakdown

Breaks down income and expenses by category group and category over an inclusive date range, with totals and percentage shares. Ungrouped categories and uncategorized transactions are included separately from named groups.

Amounts use the household's reporting currency, with expense amounts presented as positive magnitudes. Filter by accounts or tags. Hidden and deleted transactions, transactions on deleted accounts, split parents, and transfers are excluded; pending transactions are included.

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
tag_ids?array<string>|null
account_ids?array<string>|null

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/households/string/analytics/category-breakdown?start_date=2019-08-24&end_date=2019-08-24"
{  "income": {    "group_type": "income",    "total": {      "amount": "68.42",      "currency": "USD"    },    "groups": [      {        "group_id": "Cg2mV7pL4zXe",        "group_name": "Everyday Expenses",        "amount": {          "amount": "68.42",          "currency": "USD"        },        "percentage": "68.42",        "categories": [          {            "category_id": "Ct5nR8wY1jFu",            "category_name": "Coffee & Dining",            "emoji": "☕️",            "amount": {              "amount": "68.42",              "currency": "USD"            },            "percentage": "68.42"          }        ]      }    ],    "uncategorized": [      {        "category_id": "Ct5nR8wY1jFu",        "category_name": "Coffee & Dining",        "emoji": "☕️",        "amount": {          "amount": "68.42",          "currency": "USD"        },        "percentage": "68.42"      }    ]  },  "expenses": {    "group_type": "income",    "total": {      "amount": "68.42",      "currency": "USD"    },    "groups": [      {        "group_id": "Cg2mV7pL4zXe",        "group_name": "Everyday Expenses",        "amount": {          "amount": "68.42",          "currency": "USD"        },        "percentage": "68.42",        "categories": [          {            "category_id": "Ct5nR8wY1jFu",            "category_name": "Coffee & Dining",            "emoji": "☕️",            "amount": {              "amount": "68.42",              "currency": "USD"            },            "percentage": "68.42"          }        ]      }    ],    "uncategorized": [      {        "category_id": "Ct5nR8wY1jFu",        "category_name": "Coffee & Dining",        "emoji": "☕️",        "amount": {          "amount": "68.42",          "currency": "USD"        },        "percentage": "68.42"      }    ]  },  "start_date": "2019-08-24",  "end_date": "2019-08-24"}

Get Merchant Breakdown GET

Aggregates transactions by merchant over an inclusive date range and returns signed totals in the household's reporting currency with transaction counts.…

List Historical Balances GET

Retrieves daily balance history for the household, optionally restricted to specific accounts and an inclusive date range. Daily totals use the household's…