Expense Report

GET /api/v1/reports/expense

Returns expense transaction data grouped by category or entity over time periods. This endpoint provides the same data as the Expense Reports in the web UI (Expense by Category and Expense by Entity).

Query Parameters

Example Requests

Expenses by Category

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

Expenses by Entity

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

With Filters

curl -X GET "https://statements.finopsbricks.com/api/v1/reports/expense?date_from=2024-01-01&date_to=2024-12-31&group_by_field=category&category=Food&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",
      "group_by": "month",
      "group_by_field": "category"
    },
    "data": [
      {
        "category": "Food & Dining",
        "2024-01": {
          "inflow": 0,
          "outflow": 1250.50,
          "net": -1250.50,
          "transaction_count": 15
        },
        "2024-02": {
          "inflow": 0,
          "outflow": 1450.75,
          "net": -1450.75,
          "transaction_count": 18
        }
      },
      {
        "category": "Transportation",
        "2024-01": {
          "inflow": 0,
          "outflow": 450.00,
          "net": -450.00,
          "transaction_count": 8
        }
      }
    ],
    "accounts": [
      {
        "id": "acc123",
        "name": "Main Business Account",
        "category": "bank"
      },
      {
        "id": "acc456",
        "name": "Business Credit Card",
        "category": "credit_card"
      }
    ]
  }
}

Response Fields

period

data

Array of expense data grouped by the specified field (category or entity).

When group_by_field=category

Each object has:

When group_by_field=entity

Each object has:

Period Object

Each period object contains:

accounts

Array of account objects available for filtering.

Understanding Expense Data

Expense transactions are typically:

• Outflows from bank accounts or credit cards
• Negative net amounts (money going out)
• May occasionally have small inflows (refunds, corrections)

The net field (inflow - outflow) is typically negative for expense reports, representing money spent.

Filtering

Filter by Category

To view only specific categories:

?category=Food

To view uncategorized expenses:

?category=empty

Filter by Entity

To view expenses for a specific vendor/entity:

?entity=Acme Corp

To view expenses without an entity tag:

?entity=empty

Filter by Particulars

To search transaction descriptions:

?particulars=uber

This performs a partial, case-insensitive match.

Filter by Accounts

To limit to specific accounts:

?accounts=acc123,acc456

Grouping Periods

The group_by parameter determines how time periods are aggregated:

• day: Daily aggregation (e.g., "2024-01-15")
• week: Weekly aggregation (e.g., "2024-W03")
• month: Monthly aggregation (e.g., "2024-01")
• year: Yearly aggregation (e.g., "2024")

Errors