List Entities

GET /api/v1/entities

Returns transactions grouped by entity and type, with a count and inflow/outflow sum per group, over a date range. This provides the same data as the Entities 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/entities?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/entities?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": [
      {
        "entity": "Acme Corp",
        "type": "expense",
        "count": 12,
        "inflow": 0,
        "outflow": 4500.00
      },
      {
        "entity": null,
        "type": "expense",
        "count": 3,
        "inflow": 0,
        "outflow": 320.00
      }
    ],
    "totals": {
      "count": 15,
      "inflow": 0,
      "outflow": 4820.00
    },
    "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 entity aggregates. One row per distinct entity + type pair found in the range.

Field	Type	Description
entity	string \| null	Entity name, or `null` for untagged transactions
type	string	Transaction type of this group
count	number	Number of transactions in this entity+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 entities, 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