---
title: "Insights API reference"
description: "Complete reference for the analytics insights endpoints: query params, response schemas and curl examples."
canonical_url: "https://getfiga.com/help/developers/api-insights/"
---

# 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](https://getfiga.com/help/developers/api)

**No AI / LLM involved**

These endpoints return **deterministic calculations** (sums, averages, linear regression). Use them in your own reports, automations, or connected external agents through a workspace 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://api.figa.cc/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://api.figa.cc/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://api.figa.cc/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://api.figa.cc/api/v1/insights/anomalies?period=2026-02" \
  -H "x-api-key: et_live_abc123..."

# Stricter threshold (3x)
curl -X GET "https://api.figa.cc/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

This endpoint projects total spending. For individual variable bill amounts, methods and reliability, see [bill forecasts](https://getfiga.com/help/developers/api#bill-forecasts).

`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://api.figa.cc/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://api.figa.cc/api/v1/insights/summary?period=2026-02" \
  -H "x-api-key: et_live_abc123..."

# 2. Fetch comparison with previous month
curl -X GET "https://api.figa.cc/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://api.figa.cc/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://api.figa.cc/api/v1/insights/forecast?period=2026-02" \
  -H "x-api-key: et_live_abc123..."

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