GET /api/finance/trend — Monthly Time Series Data

The /api/finance/trend endpoint returns a time series of income or expense values aggregated by month, making it the right choice for any question about how a metric changes over time. When groupBy=month (the default), each row represents one calendar month across the entire company. When groupBy=department, the series is split per department so you can compare trajectories side by side — for example, to see which department’s spend grew fastest over a quarter. You can also narrow the response to specific departments using the departments filter.

Request

string

required

Which transaction type to aggregate. Must be either income or expense.

string

required

Start of the date range in YYYY-MM-DD format. Inclusive.

string

required

End of the date range in YYYY-MM-DD format. Inclusive.

string

default:"month"

Grouping dimension. Use month for a single company-wide series or department to get one series per department. Defaults to month if omitted.

string

Optional comma-separated list of department names to include. Works with both groupBy=month (narrows the company-wide aggregate to only those departments) and groupBy=department (filters which per-department series are returned). Example: Engineering,Marketing. Whitespace around commas is trimmed automatically.

Response

The response is an array of TrendPoint objects, one per month (and optionally per department). Months with no transactions are omitted rather than returned as zero-value rows.

string

The first day of the calendar month for this data point, in YYYY-MM-DD format (e.g. 2025-03-01 for March 2025).

string

The department name. Only present when groupBy=department.

number

The summed income or expense for this period (and department, if grouped).

Examples

Monthly income trend (company-wide)

curl "http://localhost:3000/api/finance/trend?metric=income&from=2025-01-01&to=2025-12-31"

[
  { "period": "2025-01-01", "value": 98500.00 },
  { "period": "2025-02-01", "value": 102300.00 }
]

Expense by department

curl "http://localhost:3000/api/finance/trend?metric=expense&groupBy=department&from=2025-01-01&to=2025-12-31"

[
  { "period": "2025-01-01", "department": "Engineering", "value": 45200.00 },
  { "period": "2025-01-01", "department": "Marketing", "value": 31800.00 },
  { "period": "2025-02-01", "department": "Engineering", "value": 47100.00 },
  { "period": "2025-02-01", "department": "Marketing", "value": 29600.00 }
]

Filter to two departments

curl "http://localhost:3000/api/finance/trend?metric=expense&groupBy=department&departments=Engineering,Marketing&from=2025-01-01&to=2025-12-31"

Error Response

{
  "error": {
    "formErrors": [],
    "fieldErrors": {
      "metric": ["Invalid enum value. Expected 'income' | 'expense', received undefined"]
    }
  }
}

​Request

​Response

​Examples

​Monthly income trend (company-wide)

​Expense by department

​Filter to two departments

​Error Response

Request

Response

Examples

Monthly income trend (company-wide)

Expense by department

Filter to two departments

Error Response