> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List and Retrieve Alerts

> List alerts, retrieve one by ID or name, look up what a set of sources supports, and inspect what an alert has delivered.

# List and Retrieve Alerts

List alerts, retrieve one, look up the available sources, filters, and triggers, and inspect what an alert has delivered.

> [!NOTE]
>
> The Python examples on this page use the original client (`metadata.ingestion.ometa.ometa_api.OpenMetadata`) because SDK 2.0 (`metadata.sdk`) doesn't include alert operations. For more information, see [Which Python SDK Should I Use?](https://docs.getcollate.io/ai-2-0/developer-guide/sdk/python.md).

## List Alerts

List the alerts in your Collate instance, optionally filtered by alert type, with `GET /v1/events/subscriptions`.

**alertType** `string`

Return only alerts of this type: `Notification` or `Observability`.

**fields** `string`

Comma-separated list of fields to include. Supported values: `owners`, `filteringRules`.

**limit** `integer` (default: 10)

Number of alerts to return in one page.

**before** `string`

Cursor for the previous page.

**after** `string`

Cursor for the next page.

## Retrieve an Alert

Retrieve one alert by ID or by name.

* By ID: `GET /v1/events/subscriptions/{id}`
* By name: `GET /v1/events/subscriptions/name/{name}`

Both accept the `fields` query parameter.

```bash GET /v1/events/subscriptions theme={null}
curl "https://your-company.getcollate.io/api/v1/events/subscriptions?alertType=Observability&limit=50&fields=filteringRules" \
  -H "Authorization: Bearer $TOKEN"
```

```python GET /v1/events/subscriptions theme={null}
from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.services.connections.metadata.openMetadataConnection import (
    OpenMetadataConnection,
)
from metadata.generated.schema.security.client.openMetadataJWTClientConfig import (
    OpenMetadataJWTClientConfig,
)
from metadata.generated.schema.events.eventSubscription import EventSubscription

server_config = OpenMetadataConnection(
    hostPort="https://your-company.getcollate.io/api",
    authProvider="openmetadata",
    securityConfig=OpenMetadataJWTClientConfig(jwtToken="<YOUR-JWT-TOKEN>"),
)
metadata = OpenMetadata(server_config)

# One alert by name
alert = metadata.get_by_name(
    entity=EventSubscription,
    fqn="dq-failed-tests-to-webhook",
)

# All alerts, paged
alerts = metadata.list_all_entities(entity=EventSubscription, limit=100)
for item in alerts:
    print(item.name, item.alertType)
```

## Available Sources, Filters, and Triggers

Ask what a set of sources supports with `POST /v1/events/subscriptions/capabilities`. Collate applies the same rules when you create the alert, so use the answer to build a valid request for [Create an Alert](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/alerts/create.md).

**alertType** `string` *required*

`Observability` or `Notification`.

**sources** `array`

Names of the sources you plan to use. Leave it empty to list every source of the alert type.

**input** `object`

The filters and triggers chosen so far, in the same shape as the alert's `input`. With it, the response warns about any selected source that none of the chosen triggers applies to.

Each source has one of three kinds:

* `entity`: changes to one asset type, such as `table` or `pipeline`. Every Observability source is an entity source.
* `activity`: the collaboration items `announcement`, `conversation`, and `task`.
* `all`: every event.

An alert combines sources of one kind only, and `all` can't be combined with other sources. A request that breaks either rule returns a `400` error that names the rule.

This request asks about an alert on pipelines and ingestion pipelines that has one trigger:

```bash theme={null}
curl -X POST "https://your-company.getcollate.io/api/v1/events/subscriptions/capabilities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alertType": "Observability",
    "sources": ["pipeline", "ingestionPipeline"],
    "input": {
      "actions": [
        {
          "name": "GetPipelineStatusUpdates",
          "effect": "include",
          "arguments": [{ "name": "pipelineStateList", "input": ["Failed"] }]
        }
      ]
    }
  }'
```

The response has these fields:

* `sources`: every source of the alert type. Each has a `name`, a `kind`, and a `selected` flag. A source you can't add to the selection has `canJoin: false` and a `reason`. A selected source that can never produce a match has a `warning`, but the alert still saves.
* `filters`: the filters every selected source supports. Each item has the filter in `condition` and the `sources` it applies to.
* `triggers`: the triggers at least one selected source supports. Each item has the trigger in `condition` and the `sources` it applies to.
* `containerEntities`: the entity types a name filter can be scoped to.
* `eventTypes`: the event types the selected sources emit.
* `recipientCategories`: who inside Collate the alert can be sent to, such as `Owners` or `Admins`.

In this shortened response, the chosen trigger applies only to `pipeline`, so `ingestionPipeline` has a warning. To clear it, add the ingestion pipeline trigger as well.

```json theme={null}
{
  "alertType": "Observability",
  "sources": [
    {
      "name": "ingestionPipeline",
      "kind": "entity",
      "selected": true,
      "canJoin": true,
      "warning": "No chosen trigger applies to this source, so none of its events match."
    },
    { "name": "pipeline", "kind": "entity", "selected": true, "canJoin": true },
    { "name": "testCase", "kind": "entity", "selected": false, "canJoin": true }
  ],
  "filters": [
    {
      "condition": { "name": "filterByOwner", "displayName": "Owner Name", "arguments": ["ownerNameList"] },
      "sources": ["pipeline", "ingestionPipeline"]
    }
  ],
  "triggers": [
    {
      "condition": { "name": "GetPipelineStatusUpdates", "displayName": "Get Pipeline Status Updates", "arguments": ["pipelineStateList"] },
      "sources": ["pipeline"]
    },
    {
      "condition": { "name": "GetIngestionPipelineStatusUpdates", "displayName": "Get Ingestion Pipeline Status Updates", "arguments": ["ingestionPipelineStateList"] },
      "sources": ["ingestionPipeline"]
    }
  ],
  "containerEntities": ["pipelineService"],
  "recipientCategories": ["Users", "Teams", "Admins", "Owners", "Followers"]
}
```

> [!NOTE]
>
> `GET /v1/events/subscriptions/{alertType}/resources` still works, but it's deprecated and will be removed in a future release. It describes each source on its own, so it can't tell you what several sources support together. Its responses include a `Deprecation` header and a `Link` header that points to the capabilities endpoint.

## Events and Delivery Status

Use these endpoints to see what an alert has processed and delivered. They require view access to all alerts. The `{id}` and `{name}` forms behave the same.

| Endpoint | Returns |
| - | - |
| `GET /v1/events/subscriptions/id/{id}/eventsRecord` | Counts of total, pending, successful, and failed events. Also available at `/name/{name}/eventsRecord`. |
| `GET /v1/events/subscriptions/id/{id}/listEvents` | Events for the alert. Filter with `status=failed` or `status=successful`. Supports `limit` (default 15) and `paginationOffset`. |
| `GET /v1/events/subscriptions/id/{id}/failedEvents` | Events that could not be delivered, with the change event, the failure reason, and the source of the failure. Also available at `/name/{name}/failedEvents`. Supports `limit`, `paginationOffset`, and `source`. |
| `GET /v1/events/subscriptions/listAllFailedEvents` | Failed events across all alerts. |
| `GET /v1/events/subscriptions/id/{id}/listSuccessfullySentChangeEvents` | Events delivered successfully. Also available at `/name/{name}/listSuccessfullySentChangeEvents`. |
| `GET /v1/events/subscriptions/id/{id}/diagnosticInfo` | Offsets (latest, current, starting), whether the alert has processed all events, and counts of unprocessed events. Also available at `/name/{name}/diagnosticInfo`. |
| `GET /v1/events/subscriptions/id/{id}/destinations` | The alert's destinations. Also available at `/name/{name}/destinations`. |
| `GET /v1/events/subscriptions/{id}/status/{destinationId}` | Status of one destination. |

Collate keeps these records for the retention period set in the Data Retention application. The default is 7 days.

## Response

Each alert includes these fields:

* `id`, `name`, and `fullyQualifiedName`
* `alertType` and `enabled`
* `resources`, `input`, and `destinations`
* `filteringRules`: the filters and triggers as expanded conditions, returned when you request it with `fields`
* `pollInterval`, `batchSize`, and `retries`
* `version`, `updatedAt`, and `updatedBy`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.