List Categories | API Documentation

GET /api/v1/categories

Returns transactions grouped by category and type, with a count and inflow/outflow sum per group, over a date range. This provides the same data as the Categories page in the web UI, as flat rows (the UI additionally nests these into a type-grouped tree client-side).

Query Parameters

Parameter	Type	Required	Default	Description
date_from	string	Yes	-	Start date (YYYY-MM-DD)
date_to	string	Yes	-	End date (YYYY-MM-DD)
accounts	string	No	all	Comma-separated account IDs to filter
type	string	No	all	Filter by transaction type (`income`, `expense`, `asset`, `liability`, `transfer`, `unknown`)

Example Requests

curl -X GET "https://statements.finopsbricks.com/api/v1/categories?date_from=2024-01-01&date_to=2024-12-31" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

curl -X GET "https://statements.finopsbricks.com/api/v1/categories?date_from=2024-01-01&date_to=2024-12-31&type=expense&accounts=acc123,acc456" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Response

{
  "data": {
    "period": {
      "date_from": "2024-01-01",
      "date_to": "2024-12-31"
    },
    "data": [
      {
        "category": "Food & Dining",
        "type": "expense",
        "count": 42,
        "inflow": 0,
        "outflow": 12500.50
      },
      {
        "category": null,
        "type": "income",
        "count": 3,
        "inflow": 250000.00,
        "outflow": 0
      }
    ],
    "totals": {
      "count": 45,
      "inflow": 250000.00,
      "outflow": 12500.50
    },
    "accounts": [
      {
        "id": "acc123",
        "name": "Main Business Account",
        "category": "bank"
      }
    ]
  }
}

Response Fields

period

Field	Type	Description
date_from	string	Start date of the range
date_to	string	End date of the range

data

Array of category aggregates. One row per distinct category + type pair found in the range.

Field	Type	Description
category	string \| null	Category name, or `null` for uncategorized transactions
type	string	Transaction type of this group
count	number	Number of transactions in this category+type
inflow	number	Sum of inflow for this group
outflow	number	Sum of outflow for this group

totals

Aggregate across all matching transactions in the range (all categories, all types).

Field	Type	Description
count	number	Total matching transactions
inflow	number	Total inflow
outflow	number	Total outflow

accounts

Array of non-archived accounts available for filtering.

Field	Type	Description
id	string	Account ID
name	string	Account name
category	string	Account category (`bank` or `credit_card`)

Errors

Code	Description
400	Missing required parameters (`date_from` or `date_to`)
400	Invalid date format (must be YYYY-MM-DD)
400	`date_from` is after `date_to`
400	Invalid `type`
401	Invalid or missing API credentials
403	API key lacks `reports:read` permission