List and Retrieve Alerts

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

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?.

List Alerts

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

string

Return only alerts of this type: Notification or Observability.

string

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

integer

default:"10"

Number of alerts to return in one page.

string

Cursor for the previous page.

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.

GET /v1/events/subscriptions

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

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.

string

required

Observability or Notification.

array

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

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:

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.

{
  "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"]
}

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

​List and Retrieve Alerts

​List Alerts

​Retrieve an Alert

​Available Sources, Filters, and Triggers

​Events and Delivery Status

​Response

List and Retrieve Alerts

List Alerts

Retrieve an Alert

Available Sources, Filters, and Triggers

Events and Delivery Status

Response