API reference

Insights

get/v1/insights

List insights

insights.listread tokenidempotent

What is worth knowing about the ledger today, most urgent first and only a handful: budgets over or nearly used, a subscription that changed price, savings-goal milestones, a budget streak, last month's recap, and categories that moved well away from the usual. Every figure comes from the ledger; nothing is stored.

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
X-Organization-Id string \| null · header

Returns 200 · InsightList

data array of Insight · required
has_more boolean · required
next_cursor string \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/insights" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

Objects

Insight

One observation that holds today.

Fields

data object · required	The facts behind it, per kind (ids such as `account_id` or `goal_id`, names, dates). Amounts are decimal strings in `data.currency`; `change`, `milestone`, `share` are ratios from 0 to 1, also as decimal strings. Keys are snake_case.
id string · required	Stable while the observation holds: its kind and its subject (`price_change:netflix`).
kind string · required	One of `budget_over`, `budget_near`, `spending_down`, `spending_up`, `price_change`, `goal_reached`, `goal_progress`, `budget_streak`, `month_recap`; new kinds may be added.
tone string · required	One of `positive`, `attention`, `neutral`: a win, something to look at, or just a fact.

InsightList

A page of insights, most urgent first.

Fields

data array of Insight · required
has_more boolean · required
next_cursor string \| null · required