---
updatedAt: 2026-11-20T20:15:32.764Z
---

Fetch the complete documentation index at: https://docs.avvio.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# The assistant's read-only insights (beta)

`GET https://api.avvio.xyz/business/api/v1/assistant/v1/{orgId}/insights/{kind}`

Exactly what the Avvio assistant answers for:
- `capacity`: can the business pay `amount` `currency` now (balance,
  limits and the approval rule together, and by how much it falls short);
- `by-person`: what each person was paid between `from` and `to`
  (YYYY-MM-DD, `to` included). Never to an AI agent key (`403`);
- `changes`: money in and payments out in the last `days` (1-30);
- `outlook`: bills and scheduled payments due in the next `days`
  (1-90), or to the end of this month with `thisMonth=true`, against
  what is available;
- `bills-open`: open bills and where each stands;
- `payments-recent`: recent payments, optionally in one `month`;
- `payments-to`: what was paid to `name` (a saved payee or an invoice's vendor);
- `recipients-check`: saved recipients that need attention;
- `currencies`: the currencies this business can pay out in, or for
  one `currency` the smallest and largest payment and the bank details
  to collect;
- `quote`: an estimate for `amount` from `from` to `to` (`receive=true`
  when `amount` is what the recipient gets);
- `month-end`: a month's payments, totals and per-payee split
  (`month`, YYYY-MM; default last month);
- `schedules`: the scheduled payments.
Parameters a kind does not take are refused.

## Parameters

- `orgId` (path, required) — The opaque organization id issued to you, normally CUID-shaped (for example `cmsx…`). It is not an `org_`-prefixed alias. Pass it unchanged in every organization-scoped path.
- `kind` (path, required)
- `amount` (query) — capacity: a decimal, e.g. 4250.00.
- `currency` (query) — capacity, currencies: ISO 4217.
- `from` (query) — by-person: first day (YYYY-MM-DD). quote: the source currency (default USD).
- `to` (query) — by-person: last day, included (YYYY-MM-DD). quote: the payout currency.
- `receive` (query) — quote: amount is what the recipient gets.
- `days` (query) — changes (1-30, default 1) or outlook (1-90, default 14).
- `thisMonth` (query) — outlook: to the end of the calendar month.
- `month` (query) — payments-recent: only payments paid (or prepared) in that month.
- `name` (query) — payments-to: the payee or vendor name.

## Example

```bash
curl -s "$AVVIO_BASE_URL/assistant/v1/$AVVIO_ORG_ID/insights/$kind" \
  -H "x-api-key: $AVVIO_API_KEY"
```

## Responses

- `200` — The insight, as the assistant reads it (beta; fields may be added).
- `400` — `VALIDATION_ERROR`: a query parameter was refused, and `errors` names it. A `limit` outside its range is refused, not clamped; a `cursor` we did not issue for this organization is refused (start from the first page); an unknown filter value or a parameter sent twice is refused.
- `401` — The key was refused. Nothing ran. - `UNAUTHORIZED`: missing, invalid or revoked, or a key on a route that does not accept one. - `KEY_EXPIRED`: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated. - `KEY_IP_NOT_ALLOWED`: the key is pinned to source addresses and this request came from another.
- `403` — A valid key that may not make this call. Nothing ran. - `FORBIDDEN`: the key belongs to a different organization. - `ACCOUNT_BLOCKED`: API access for your organization is suspended, and every key is refused until we lift it. Contact support.
- `404` — No such insight.
- `429` — Too many requests. The default ceiling is **100 requests per minute per API credential** on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies. Obey `Retry-After`; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same `Idempotency-Key`.

Machine contract: [partner-payouts.openapi.yaml](/partner-payouts.openapi.yaml), operation `getAssistantInsight`.
