# List alerts > The alerts.list operation: GET /api/v1/alerts in the REST API and the alerts_list tool in the MCP server. Lists the organization's alerts in the mode of the request, newest first: the console inbox (spec §24), by default the unresolved ones (open or acknowledged). Only the alerts your role may see are listed: each alert is about one area (registrations, ledger, webhooks, …, its `family`) and is shown to members who may read that area at its legal entity or brand. Owners and admins see every alert. By default only unresolved alerts (`open` and `acked`); filter with `status` (one or several), `severity`, `code` or `entityId`. Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page); a page can be shorter than `limit` while `has_more` is true. ## At a glance - **REST:** `GET /api/v1/alerts` - **MCP tool:** `alerts_list` - **Operation ID:** `alerts.list` - **Scope:** Organization - **Permission:** `org:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Pagination:** `limit` (at most 100) and `starting_after` - **Authentication:** API key with the `org:read` scope - **Since:** M7 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | --------------------------------------------------------------------------------- | -------- | ----------- | | `limit` | integer (1 to 100) | No | | | `starting_after` | `alr_…` ID | No | | | `status` | one of `open`, `acked`, `resolved` or array of one of `open`, `acked`, `resolved` | No | | | `severity` | one of `info`, `high`, `critical` or array of one of `info`, `high`, `critical` | No | | | `code` | string | No | | | `entityId` | `ent_…` ID | No | | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------- | ----------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | `alr_…` ID | | | `data[].object` | `"alert"` | | | `data[].code` | string | | | `data[].severity` | one of `info`, `high`, `critical` | | | `data[].family` | one of 14 values, e.g. `registrations`, `filings`, `ledger` (all in the OpenAPI document) | | | `data[].message` | string | | | `data[].link` | string | | | `data[].entityId` | `ent_…` ID or null | | | `data[].brandId` | `brd_…` ID or null | | | `data[].livemode` | boolean | | | `data[].status` | one of `open`, `acked`, `resolved` | | | `data[].occurrences` | integer (at least 1) | | | `data[].lastRaisedAt` | date-time | | | `data[].acknowledgedAt` | date-time or null | | | `data[].acknowledgedBy` | string or null | | | `data[].resolvedAt` | date-time or null | | | `data[].resolvedBy` | string or null | | | `data[].delivery` | object | | | `data[].delivery.status` | one of `none`, `pending`, `delivered`, `failed` | | | `data[].delivery.attempts` | integer (at least 0) | | | `data[].delivery.lastError` | string or null | | | `data[].delivery.email` | object | | | `data[].delivery.email.sent` | integer (at least 0) | | | `data[].delivery.email.failed` | integer (at least 0) | | | `data[].delivery.slack` | array of object | | | `data[].delivery.slack[].channelId` | string | | | `data[].delivery.slack[].status` | one of `sent`, `failed` | | | `data[].delivery.slack[].at` | date-time | | | `data[].delivery.slack[].error` | string or null | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `data[].version` | integer (at least 1) | | | `has_more` | boolean | | | `next_cursor` | `alr_…` ID or null | | ## Examples ### The unresolved alerts ```http GET /api/v1/alerts Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "alr_01m4ttwd3veh9apbewxheq5xab", "object": "alert", "code": "REG_AUTO_BLOCKED", "severity": "critical", "family": "registrations", "message": "EU_OSS_NON_UNION was blocked for new consumer sales on 2026-11-07: the grace deadline 2026-11-10 is near and no application was submitted.", "link": "/console/acme/e/acme-hr/jurisdictions/EU_OSS_NON_UNION", "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4", "brandId": null, "livemode": true, "status": "open", "occurrences": 1, "lastRaisedAt": "2026-10-13T12:00:00.000Z", "acknowledgedAt": null, "acknowledgedBy": null, "resolvedAt": null, "resolvedBy": null, "delivery": { "status": "delivered", "attempts": 1, "lastError": null, "email": { "sent": 2, "failed": 0 }, "slack": [ { "channelId": "sec_01m4ttwd3veh9apbewxheq5xad", "status": "sent", "at": "2026-10-13T12:00:00.000Z", "error": null } ] }, "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z", "version": 1 } ], "has_more": false, "next_cursor": null } ``` ### Critical alerts of one legal entity, including resolved ones ```http GET /api/v1/alerts?severity=critical&status=open&status=acked&status=resolved&entityId=ent_01m4ttwd3veh9apbewxheq5xh4&limit=1 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "alr_01m4ttwd3veh9apbewxheq5xab", "object": "alert", "code": "REG_AUTO_BLOCKED", "severity": "critical", "family": "registrations", "message": "EU_OSS_NON_UNION was blocked for new consumer sales on 2026-11-07: the grace deadline 2026-11-10 is near and no application was submitted.", "link": "/console/acme/e/acme-hr/jurisdictions/EU_OSS_NON_UNION", "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4", "brandId": null, "livemode": true, "status": "open", "occurrences": 1, "lastRaisedAt": "2026-10-13T12:00:00.000Z", "acknowledgedAt": null, "acknowledgedBy": null, "resolvedAt": null, "resolvedBy": null, "delivery": { "status": "delivered", "attempts": 1, "lastError": null, "email": { "sent": 2, "failed": 0 }, "slack": [ { "channelId": "sec_01m4ttwd3veh9apbewxheq5xad", "status": "sent", "at": "2026-10-13T12:00:00.000Z", "error": null } ] }, "createdAt": "2026-10-13T12:00:00.000Z", "updatedAt": "2026-10-13T12:00:00.000Z", "version": 1 } ], "has_more": true, "next_cursor": "alr_01m4ttwd3veh9apbewxheq5xab" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or pagination value is invalid. | Fix the fields listed in `details.issues` and send the request again. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't read this organization's inbox. | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).