Insights API reference

Five read-only analytics endpoints that compute deterministic aggregations from expense data. All require expenses.read permission and accept a workspace-scoped API key.

← Back to API reference

No AI / LLM involved

These endpoints return deterministic calculations (sums, averages, linear regression). The conversational AI chat (/ai/chat) is a separate feature available only through the web UI, not via API key.

Summary

GET /api/v1/insights/summary · Permission: expenses.read

Spending summary for a single month with category and recipient breakdowns.

Query parameters

Param	Type	Required	Description
`period`	string	Yes	Month in `YYYY-MM` format (e.g. `2026-02`).

Example request

curl -X GET "https://app.figa.io/api/v1/insights/summary?period=2026-02" \
  -H "x-api-key: et_live_abc123..."

Response

{
  "period": "2026-02",
  "total": 854250,
  "count": 24,
  "paid": 18,
  "unpaid": 6,
  "byCategory": [
    { "name": "Housing",  "amount": 420000, "count": 1, "pct": 49 },
    { "name": "Cloud",    "amount": 214250, "count": 5, "pct": 25 },
    { "name": "Food",     "amount": 120000, "count": 12, "pct": 14 },
    { "name": "Software", "amount": 100000, "count": 6,  "pct": 12 }
  ],
  "byRecipient": [
    { "name": "WeWork",  "amount": 420000, "count": 1 },
    { "name": "AWS",     "amount": 142500, "count": 3 },
    { "name": "Hetzner", "amount": 71750,  "count": 2 }
  ]
}

Response fields

Field	Type	Description
`period`	string	Requested period.
`total`	integer	Total amount in cents.
`count`	integer	Total expense count.
`paid`	integer	Number of paid expenses.
`unpaid`	integer	Number of unpaid expenses.
`byCategory[]`	array	Breakdown by category, sorted by amount descending.
`.name`	string	Category name.
`.amount`	integer	Total in cents.
`.count`	integer	Expense count in this category.
`.pct`	integer	Percentage of total (0–100).
`byRecipient[]`	array	Breakdown by recipient, sorted by amount descending.
`.name`	string	Recipient name.
`.amount`	integer	Total in cents.
`.count`	integer	Expense count for this recipient.

Comparison

GET /api/v1/insights/comparison · Permission: expenses.read

Compare two months with absolute/percentage differences and per-category change breakdown.

Query parameters

Param	Type	Required	Description
`p1`	string	Yes	First period in `YYYY-MM` format.
`p2`	string	Yes	Second period in `YYYY-MM` format (baseline for % calculation).

Example request

curl -X GET "https://app.figa.io/api/v1/insights/comparison?p1=2026-02&p2=2026-01" \
  -H "x-api-key: et_live_abc123..."

Response

{
  "p1": {
    "period": "2026-02", "total": 854250, "count": 24,
    "paid": 18, "unpaid": 6,
    "byCategory": [ ... ],
    "byRecipient": [ ... ]
  },
  "p2": {
    "period": "2026-01", "total": 790000, "count": 22,
    "paid": 22, "unpaid": 0,
    "byCategory": [ ... ],
    "byRecipient": [ ... ]
  },
  "diff": 64250,
  "diffPct": 8.1,
  "categoryChanges": [
    { "name": "Cloud",   "p1": 214250, "p2": 180000, "diff": 34250,  "diffPct": 19.0 },
    { "name": "Food",    "p1": 120000, "p2": 130000, "diff": -10000, "diffPct": -7.7 },
    { "name": "Housing", "p1": 420000, "p2": 420000, "diff": 0,      "diffPct": 0 }
  ]
}

Response fields

Field	Type	Description
`p1`	Summary	Full summary object for first period.
`p2`	Summary	Full summary object for second period (baseline).
`diff`	integer	Absolute difference in cents (`p1.total − p2.total`).
`diffPct`	number	Percentage change relative to p2 (1 decimal).
`categoryChanges[]`	array	Per-category changes, sorted by absolute diff descending.
`.name`	string	Category name.
`.p1`	integer	Amount in p1 (cents).
`.p2`	integer	Amount in p2 (cents).
`.diff`	integer	Difference in cents.
`.diffPct`	number	Percentage change (1 decimal).

Trends

GET /api/v1/insights/trends · Permission: expenses.read

Multi-month trend analysis with linear regression. Returns overall direction and per-category trends.

Query parameters

Param	Type	Required	Description
`months`	integer	No	Number of months to analyze (2–24). Default: `6`.

Example request

curl -X GET "https://app.figa.io/api/v1/insights/trends?months=12" \
  -H "x-api-key: et_live_abc123..."

Response

{
  "months": [
    { "period": "2025-03", "total": 680000 },
    { "period": "2025-04", "total": 720000 },
    { "period": "2025-05", "total": 710000 },
    { "period": "2025-06", "total": 780000 },
    { "period": "2025-07", "total": 810000 },
    { "period": "2025-08", "total": 854250 }
  ],
  "avgMonthly": 759042,
  "trend": "up",
  "trendPct": 8.4,
  "categoryTrends": [
    { "name": "Cloud",    "trend": "up",     "trendPct": 15.2 },
    { "name": "Food",     "trend": "stable", "trendPct": 2.1 },
    { "name": "Housing",  "trend": "stable", "trendPct": 0 },
    { "name": "Software", "trend": "down",   "trendPct": 6.8 }
  ]
}

Response fields

Field	Type	Description
`months[]`	array	Monthly totals in chronological order.
`.period`	string	Month (`YYYY-MM`).
`.total`	integer	Total amount in cents.
`avgMonthly`	integer	Average monthly amount in cents.
`trend`	string	`"up"` (>5%), `"down"` (<−5%), or `"stable"`.
`trendPct`	number	Absolute trend percentage (1 decimal). Calculated via linear regression.
`categoryTrends[]`	array	Per-category trends, sorted by trendPct descending.
`.name`	string	Category name.
`.trend`	string	`"up"`, `"down"`, or `"stable"`.
`.trendPct`	number	Absolute trend percentage (1 decimal).

Trend calculation

Trend direction is determined by linear regression across all months. The percentage represents the total change from first to last month relative to the first month's value. Thresholds: > 5% = up, < −5% = down, otherwise stable.

Anomalies

GET /api/v1/insights/anomalies · Permission: expenses.read

Detects unusually large expenses using two methods: (1) comparison against 6-month historical average per category, (2) median-based intra-period outlier detection.

Query parameters

Param	Type	Required	Description
`period`	string	Yes	Month in `YYYY-MM` format.
`threshold`	number	No	Multiplier threshold (1–10). Default: `2.0`. Expense flagged when amount ≥ threshold × average.

Example requests

# Default threshold (2x)
curl -X GET "https://app.figa.io/api/v1/insights/anomalies?period=2026-02" \
  -H "x-api-key: et_live_abc123..."

# Stricter threshold (3x)
curl -X GET "https://app.figa.io/api/v1/insights/anomalies?period=2026-02&threshold=3" \
  -H "x-api-key: et_live_abc123..."

Response

{
  "period": "2026-02",
  "anomalies": [
    {
      "expense": {
        "id": "Emergency server-1740009600000",
        "name": "Emergency server",
        "amount": 450000
      },
      "reason": "4.7x średnia dla kategorii Cloud",
      "avgForCategory": 95744
    },
    {
      "expense": {
        "id": "Team offsite-1740268800000",
        "name": "Team offsite",
        "amount": 280000
      },
      "reason": "3.1x mediana wydatków w okresie",
      "avgForCategory": 90000
    }
  ]
}

Response fields

Field	Type	Description
`period`	string	Requested period.
`anomalies[]`	array	Detected anomalies, sorted by ratio (highest first). Empty array if none found.
`.expense.id`	string	Generated identifier.
`.expense.name`	string	Expense name.
`.expense.amount`	integer	Amount in cents.
`.reason`	string	Human-readable explanation, e.g. `"4.7x średnia dla kategorii Cloud"` or `"3.1x mediana wydatków w okresie"`.
`.avgForCategory`	integer	The reference average or median used for comparison (cents).

Detection methods

Method	Logic	reason prefix
Historical	Compares each expense against the 6-month average for its category.	`Nx średnia dla kategorii X`
Intra-period	Uses median of all expenses in the period. Catches outliers without history.	`Nx mediana wydatków w okresie`

Forecast

GET /api/v1/insights/forecast · Permission: expenses.read

Linear projection of current spending to full month, plus scheduled recurring expenses that haven't been paid yet.

Query parameters

Param	Type	Required	Description
`period`	string	Yes	Month in `YYYY-MM` format.

Example request

curl -X GET "https://app.figa.io/api/v1/insights/forecast?period=2026-02" \
  -H "x-api-key: et_live_abc123..."

Response

{
  "period": "2026-02",
  "currentTotal": 520000,
  "daysElapsed": 16,
  "daysRemaining": 12,
  "projectedTotal": 910000,
  "upcomingRecurring": [
    { "name": "Netflix",     "amount": 4999,   "dueDate": "2026-02-20" },
    { "name": "Office rent", "amount": 420000, "dueDate": "2026-03-01" }
  ],
  "projectedWithRecurring": 1334999
}

Response fields

Field	Type	Description
`period`	string	Requested period.
`currentTotal`	integer	Amount spent so far (cents).
`daysElapsed`	integer	Days passed in the period.
`daysRemaining`	integer	Days left in the period.
`projectedTotal`	integer	Linear projection: `(currentTotal / daysElapsed) × daysInMonth`.
`upcomingRecurring[]`	array	Unpaid recurring expenses still due this month, sorted by date.
`.name`	string	Recurring expense name.
`.amount`	integer	Amount in cents.
`.dueDate`	string	Due date (`YYYY-MM-DD`).
`projectedWithRecurring`	integer	`projectedTotal + sum(upcomingRecurring.amount)`.

Projection logic

For the current month, daysElapsed is today's date and upcomingRecurring only includes items scheduled after today. For past months, the full month is used and there are no upcoming items. For future months, currentTotal is 0 and all recurring items are listed.

Integration examples

Monthly Slack report (Make / n8n)

Fetch summary at end of month and post to Slack.

# 1. Fetch summary for current month
curl -X GET "https://app.figa.io/api/v1/insights/summary?period=2026-02" \
  -H "x-api-key: et_live_abc123..."

# 2. Fetch comparison with previous month
curl -X GET "https://app.figa.io/api/v1/insights/comparison?p1=2026-02&p2=2026-01" \
  -H "x-api-key: et_live_abc123..."

# 3. Format and send to Slack webhook

Spending anomaly alert

Run daily/weekly to catch unusual expenses early.

# Flag expenses exceeding 3x category average
curl -X GET "https://app.figa.io/api/v1/insights/anomalies?period=2026-02&threshold=3" \
  -H "x-api-key: et_live_abc123..."

# If anomalies[] is non-empty → send alert

Budget projection dashboard

Combine forecast with trends for a dashboard widget.

# Current month projection
curl -X GET "https://app.figa.io/api/v1/insights/forecast?period=2026-02" \
  -H "x-api-key: et_live_abc123..."

# 12-month trend for chart
curl -X GET "https://app.figa.io/api/v1/insights/trends?months=12" \
  -H "x-api-key: et_live_abc123..."