# Insights API

Evidence-backed account insights and their lifecycle actions.

> **Scope of this file.** It is the OPERATION reference for THIS resource, generated from the BillerAPI OpenAPI document served at [/docs/openapi.json](/docs/openapi.json): each API-key endpoint the resource owns, with its parameters, request body, responses and schemas. Narrative and catalog sections the rendered page also carries (walkthroughs, event taxonomies, payload catalogs) are NOT reproduced here — read [/docs/api/insights](/docs/api/insights) for those. Endpoints the hosted flow drives from inside the iframe, and dashboard-session endpoints, are absent by design: they are not API-key operations. [/docs/api.md](/docs/api.md) enumerates the full API-key surface, including the endpoints that have no reference page yet.

All request and response field names are snake_case. Errors use the coded envelope described in [/docs/concepts/errors.md](/docs/concepts/errors.md).

## Endpoints

- [`GET /v1/insights`](#get-v1insights)
- [`GET /v1/insights/{id}`](#get-v1insightsid)
- [`POST /v1/insights/{id}/snooze`](#post-v1insightsidsnooze)
- [`POST /v1/insights/{id}/dismiss`](#post-v1insightsiddismiss)
- [`POST /v1/insights/{id}/resolve`](#post-v1insightsidresolve)

## GET /v1/insights

List insights for an account

Returns insights for a specific account (account_id) under one of your biller connections (account_link_id), newest first. Both account_link_id and account_id are required. Optionally filter by user_aid and status. Cursor-paginated.

Operation ID: `listInsights`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `account_link_id` | query | yes | string | — | The account_link_id (biller connection) to list insights for. |
| `account_id` | query | yes | string | — | The account_id (the account within the connection) to list insights for. |
| `user_aid` | query | no | string | — | Optional filter to insights for a specific end-user (your client_user_id). |
| `status` | query | no | `OPEN` \| `SNOOZED` \| `DISMISSED` \| `RESOLVED` | — | Filter by lifecycle status. |
| `limit` | query | no | number | — | Maximum number of insights to return (1-100). |
| `cursor` | query | no | string | — | Opaque pagination cursor from a prior response. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | List of insights | `object` |

Response body — `object` (200)

Example:

```json
{
  "insights": [
    {
      "id": "insight_01HX5...",
      "user_aid": "user_42",
      "account_link_id": "alink_01HX...",
      "account_id": "acct_01HX...",
      "biller_id": "test_electric_company",
      "bill_id": "bill_01HX...",
      "type": "duplicate_charge",
      "severity": "warn",
      "status": "OPEN",
      "evidence": {},
      "proposed_actions": [
        {
          "action_type": "review_bill",
          "label": "Review bill",
          "params": {}
        }
      ],
      "reasoning": "Two charges of the same amount within 24h.",
      "created_at": "2026-06-13T12:00:00.000Z",
      "snoozed_until": null,
      "resolved_at": null
    }
  ],
  "has_more": false,
  "next_cursor": ""
}
```


## GET /v1/insights/{id}

Get an insight by id

Returns a single insight with full evidence, proposed actions, and reasoning. Cross-tenant lookups return 404 (no existence leak).

Operation ID: `getInsightById`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | yes | string | — | — |
| `user_aid` | query | yes | string | — | — |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | Insight detail | — |
| 404 | Insight not found | — |

## POST /v1/insights/{id}/snooze

Snooze an insight

Snooze the insight until a future instant. Idempotent on the same `until`.

Operation ID: `snoozeInsight`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | yes | string | — | — |
| `user_aid` | query | yes | string | — | — |

**Request body** (required)

Schema: `SnoozeInsightBodyDto`

| Field | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `until` | yes | string | — | ISO-8601 instant to snooze the insight until. Must be in the future. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | Snoozed insight | — |
| 404 | Insight not found | — |

## POST /v1/insights/{id}/dismiss

Dismiss an insight

Dismiss the insight (terminal). Idempotent once dismissed.

Operation ID: `dismissInsight`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | yes | string | — | — |
| `user_aid` | query | yes | string | — | — |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | Dismissed insight | — |
| 404 | Insight not found | — |

## POST /v1/insights/{id}/resolve

Resolve an insight

Resolve the insight. Terminal after a dismiss (the user action wins).

Operation ID: `resolveInsight`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | yes | string | — | — |
| `user_aid` | query | yes | string | — | — |

**Request body** (required)

Schema: `ResolveInsightBodyDto`

| Field | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `resolved_at` | no | string | — | Optional ISO-8601 instant the insight was resolved at. Defaults to server-now. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | Resolved insight | — |
| 404 | Insight not found | — |

## Schemas

### ResolveInsightBodyDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `resolved_at` | no | string | — | Optional ISO-8601 instant the insight was resolved at. Defaults to server-now. |

### SnoozeInsightBodyDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `until` | yes | string | — | ISO-8601 instant to snooze the insight until. Must be in the future. |


## See also

- [API reference index](/docs/api.md)
- [Authentication](/docs/guides/authentication.md)
- [Pagination](/docs/concepts/pagination.md)
- [Error handling](/docs/concepts/errors.md)