GET /insights— a computed report over every customer under your API key: snapshot KPIs with previous-period deltas, daily time series, observations and advisory suggestions attributed to the customer they concern, and a roll-up row per customer. No LLM anywhere in this path — every number, date and sentence is computed deterministically from your customers’ own objects.
Beta — part of the agentic early-access surface, like the rest of the Insights tag. The report is read-only by construction: it cannot move money, create, or change anything. It reads scheduled payments, mandates, wallets, customers and recipients, so it needs an
admin-role API key — a viewer key is refused with 403.The report
The report is a view, not a stored object — computed on demand from your customers’ scheduled payments, mandates, recipients, wallets and balances. There is nothing to create, poll into existence, or clean up. The client is resolved from the API key; there is no path parameter.snapshot— typed facts for stat cards.customersdescribes the population behind the report (see Scan cap);metrics[]are the KPIs over the window with the previous window’s value and achange_pctfor trend rendering. Count metrics (executed_payments,failed_payments,new_counterparties) appear once; amount metrics (executed_volume) appear once per asset. With?customer_id=the snapshot also carries that customer’s per-walletbalances.series— daily buckets for charts. Keys are an open set:<metric>for counts and<metric>.<ASSET>for amounts (executed_payments,failed_payments,executed_volume.<ASSET>over the window, andupcoming_obligations.<ASSET>looking forward over the nextwindow_days— an overdue open payment is not plotted there; it is counted insnapshot.upcomingand surfaces aspayment_at_risk).tis the bucket’s UTC midnight — format labels in UTC.facets— the kinds, severities, responsibilities and assets present in the report, computed before any item filter is applied, so a filter menu keeps offering every option while a filter is active.insights[]— observations: what is happening, across the book.suggestions[]— advice: what a customer may want to do. Always advisory — acting on one is a separate, human-gated step through the normal payment flow.customers[]— one roll-up row per scanned customer (balance, open payments, active mandates, upcoming totals, finding counts by severity, last executed payment), sorted worst-first: critical count, then warn count, then most recent activity. Use it for the drill-down table.
Items are the customer report’s items
insights[] and suggestions[] use the same item schema as Account Insights — {kind, severity, message, detail, evidence} — with two additive fields at this scope:
customer_id— the customer the item is about. Omitted on cross-customer aggregates, which list the affected customers indetail.customer_idsinstead.responsibility— a coarse grouping label (payment_opsorcompliance) for filtering and routing. It is a label only; it carries no ownership semantics.
severity is closed (info | warn | critical), kind and evidence.type are open sets (render an unrecognized value generically, never drop it), message is a complete sentence, detail carries the raw values behind it.
What the client report adds
Every kind in the customer kind catalog appears here per customer. On top of those:
Failure items carry the failure code. Clustered failure items add
detail.failure_code — the same stable code the scheduled_payment.failed webhook carries — whenever the stored reason maps to a documented code; every failure item, including the payments_failed singleton summary, carries detail.docs_url pointing at that reference, so a UI can link straight from a finding to what to do about it. Cross-customer clusters group on the code (or on the reason text when no code applies), so two customers denied by different mandate rules still surface as one finding.
Filters
Every filter is optional and only narrows the report; the response shape never changes.
Multi-value filters are OR within a field and AND across fields:
severity=critical,warn&responsibility=payment_ops keeps critical-or-warn items that belong to payment ops. kind, severity, responsibility and wallet_id drop only items — snapshot, series, facets and customers[] are the facts of the book and stay whole, so a filtered view still shows the right totals.
Scan cap
One request scans up to 100 customers, in your customer list’s order (name, then id).snapshot.customers makes that visible: scanned < total means the cap truncated the book and the report describes that prefix of it — truncation is never silent. with_activity counts customers with any non-cancelled scheduled payment within the 180-day read, or any finding; with_critical counts customers carrying at least one critical item. Use ?customer_id= to compute a full report for any customer, scanned or not.
The payments read behind each customer reaches back 180 days — the widest window plus the anomaly baseline behind it. A recipient silent for longer than that ages out of recipient_dormant rather than being reported forever.
Degradation, not errors
A deployment without a balance index simply omits balance-derived parts (total_usd, balances, shortfall math); the rest of the report still computes. Missing data degrades the report — it never 500s.
Customer or client report?
Render the client report for the operator’s view: KPI tiles with deltas, charts fromseries, a findings feed sorted by severity, and a customers table that drills into ?customer_id=. Render the customer report — or the drilled-down client report, which carries the same items for that customer — inside a single customer’s own experience. The two always agree: the client report is built from the same per-customer computation.