Ataccama ONE Agentic ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
Downloads

Monitor Data Observability Alerts via API

The REST API is currently in Early Access Preview. The API specification and endpoints might change before being marked as stable.

We recommend testing thoroughly and being prepared to adapt to potential changes in future releases.

This guide shows you how to programmatically list and filter data observability alerts, retrieve their details, and drill down into the findings behind each alert. This enables you to route alerts into external tools, such as ticketing or incident management systems, and follow each alert down to the affected assets.

Through the API, alerts and their findings are read-only. The current version of the API is designed for monitoring and reporting. The following actions are possible only in the web application:

Prerequisites

Before using the Data Observability API:

  • Configure authentication as described in API Authentication.

  • Assign the API client the dataobservability-admin identity provider role, the same role that grants access to data observability in the web application (see Identity Provider Roles). Data observability currently has no read-only role, so this role is required even though the API is read-only.

API base URL

All Data Observability API endpoints are accessed through the following base URL:

https://{your-environment}.ataccama.one/api/data-observability/v1

Replace {your-environment} with your environment identifier from the Ataccama Cloud Portal.

When to use this API

Use the alerts API when you need to:

  • Integrate alerts into external tooling: Forward alerts and their findings to ticketing or incident management systems (see Poll for new alerts and changes).

  • Drill down from an alert to its findings: Identify the affected assets and route the issue to the right team (see Drill down from an alert to the affected assets).

  • Build operational dashboards: Retrieve alerts by status, resolution, finding type, affected asset, or time range, and aggregate them in your BI tool.

  • Audit alert history: Retrieve alerts and their findings for compliance or internal audits.

Alerts and findings

A finding is an individual problem detected over the observed data and pipelines, such as a DQ threshold breach, a pipeline failure, or a freshness, schema, or volume anomaly. An alert groups related findings, so your team handles one alert instead of many separate signals. For how findings are grouped and how alerts relate to notifications, see Key concepts of alerts and notifications.

Statuses, severities, resolutions, and finding types are extensible sets. New values might be added over time, so make sure your integration handles unknown values gracefully.

The values are also case-sensitive. Send them exactly as listed in Alert fields and Finding fields.

Alert fields

Field Description

urn

The URN of the alert, in the format urn:ata:{tenant}:data-observability:alert:{uuid}.

status

The alert lifecycle status, taken from the findings:

  • ACTIVE: One or more of the alert’s findings are still active.

  • STALE: None of the alert’s findings are active, but one or more are stale.

  • INACTIVE: All of the alert’s findings are inactive, and the alert has ended.

severity

The highest severity among the alert’s findings: LOW, MEDIUM, HIGH, or CRITICAL.

resolution

How your team triaged the alert, as set in the web application (see Investigate Alerts):

  • NOT_SET: The resolution has not been decided yet.

  • OPEN: The alert requires attention.

  • EXPECTED: The behavior is acceptable and aligns with expectations.

  • FALSE_POSITIVE: The alert was triggered incorrectly and does not reflect a real problem.

  • RESOLVED: The underlying cause has been addressed.

  • ESCALATED: The alert has been escalated to Jira or ServiceNow.

createdAt

When the alert was created.

updatedAt

When the alert’s findings were last updated. The timestamp tracks updates to the findings only, not changes to the alert’s resolution.

resolvedAt

When the alert was last resolved. Omitted while the alert is unresolved.

findingUrns

The URNs of the findings grouped under the alert, capped at 1000 entries and not paginated. Returned by Retrieve an alert only.

To get the findings with their attributes, list them with the alertUrn parameter instead (see List findings).

Finding fields

Field Description

urn

The URN of the finding, in the format urn:ata:{tenant}:data-observability:finding:{uuid}.

alertUrn

The URN of the alert the finding belongs to. Every finding is currently attached to an alert, but treat the field as optional for forward compatibility.

findingType

The type of the finding as a hierarchical, dot-separated code, for example, data.dq.threshold-breach-rule or job.failure. See Finding types.

severity

The severity of the finding: LOW, MEDIUM, HIGH, or CRITICAL.

status

The finding lifecycle status:

  • ACTIVE: The problem is still being observed.

  • STALE: The problem has not been observed recently.

  • INACTIVE: The problem has ended (see endedAt).

summary

A human-readable summary of the finding, for example, Completeness on customer.email dropped to 71% (threshold 95%).

affectedAssetUrn

The URN of the affected asset. The URN shows the asset’s API area and resource type:

  • catalog:catalog-item: DQ and freshness findings.

  • pipeline-monitoring:pipeline-job: Job failures and cancellations.

  • pipeline-monitoring:dataset: Schema changes and observed-data findings.

To get the details of a catalog item, see Catalog Items API. To get the details of a pipeline job or dataset, see Pipeline Monitoring API.

firstSeenAt, lastSeenAt

When the problem was first observed and when it was last observed.

endedAt

When the problem ended. Set only once the finding is INACTIVE; omitted while it is ACTIVE or STALE.

createdAt

When the finding was registered. This is the default sort field; it can differ from firstSeenAt by ingest lag.

Finding types

Finding types are hierarchical, dot-separated codes. A parent code, such as data.dq, groups the subtypes under it.

The following finding types are available:

Code Meaning

data

All data findings, as opposed to pipeline job findings.

data.da

Data anomaly findings.

data.da.freshness

Freshness findings.

data.da.freshness.anomaly

A freshness anomaly.

data.da.freshness.sla

A freshness SLA breach.

data.da.profiling

Profiling anomaly findings.

data.da.profiling.attribute

An anomaly detected on an attribute.

data.da.profiling.ci

An anomaly detected on a catalog item, such as a number of records anomaly.

data.dq

Data quality findings.

data.dq.threshold-breach-ci

A DQ monitor dropped below its threshold on a catalog item.

data.dq.threshold-breach-rule

A rule instance dropped below its threshold.

data.schema-change

Schema change findings.

data.schema-change.asset

Asset-level schema changes.

data.schema-change.asset.created

A monitored asset was created.

data.schema-change.asset.deleted

A monitored asset was deleted.

data.schema-change.attribute

Attribute-level schema changes.

data.schema-change.attribute.added

An attribute was added.

data.schema-change.attribute.changed

An attribute was changed.

data.schema-change.attribute.deleted

An attribute was deleted.

data.schema-change.attribute.type-changed

The data type of an attribute changed.

job

Pipeline job findings.

job.abort

A pipeline job was canceled.

job.failure

A pipeline job failed.

job.updated

A pipeline job was updated.

Wherever you filter by finding type, the match includes the exact code and all its subtypes. For example, filtering by data.dq also matches data.dq.threshold-breach-rule. Even the equals operator matches subtypes, not just the exact code. The notEquals and notIn operators are not supported and are ignored if sent.

The set of codes is fixed within a release but can change between releases. Make sure your integration handles unknown values gracefully.

List alerts

List the alerts in your environment.

To restrict the result by status, severity, or resolution, use the corresponding query parameters. Each parameter accepts a single value. For multi-value or negated conditions, or to filter by finding type, affected asset, or creation date, use Filter alerts instead.

Request: List active alerts
curl -X GET "https://{your-environment}.ataccama.one/api/data-observability/v1/alerts?status=ACTIVE&size=20" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

status

string

No

Restricts the result to alerts with the given status (ACTIVE, STALE, or INACTIVE).

severity

string

No

Restricts the result to alerts with the given severity (LOW, MEDIUM, HIGH, or CRITICAL).

resolution

string

No

Restricts the result to alerts with the given resolution (NOT_SET, OPEN, EXPECTED, FALSE_POSITIVE, RESOLVED, or ESCALATED).

size

integer

No

Number of alerts to return per page.

Default: 20.

Max: 100.

sort

string

No

Field to sort by; prefix with a hyphen (-) for descending order. Only createdAt is supported, and only one field per request.

Default: -createdAt (newest first).

after

string

No

Cursor for forward pagination. Use the value from meta.next in the previous response.
Response: Page of alerts
{
  "meta": {
    "next": "MjA=",
    "total": 42
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:data-observability:alert:0197f3a0-1111-7c0c-8f9d-3a2b4c5d6e7f",
      "status": "ACTIVE",
      "severity": "CRITICAL",
      "resolution": "OPEN",
      "createdAt": "2026-07-09T06:15:00Z",
      "updatedAt": "2026-07-10T05:40:00Z"
    },
    {
      "urn": "urn:ata:{your-tenant}:data-observability:alert:0197f3a0-3333-7c0c-8f9d-3a2b4c5d6e7f",
      "status": "ACTIVE",
      "severity": "MEDIUM",
      "resolution": "NOT_SET",
      "createdAt": "2026-07-10T02:05:00Z",
      "updatedAt": "2026-07-10T02:05:00Z"
    }
  ]
}

The response contains a data array with up to size alerts, and a meta object with the pagination information:

  • meta.next: Cursor for retrieving the next batch of alerts. Pass it as the after parameter in the next request. Omitted when there are no more alerts to retrieve.

  • meta.total: Total number of matching alerts, across all pages.

Filter rules

The filter endpoints, Filter alerts and Filter findings, share the same filter format. The table in each section lists the fields you can filter by and the operators each field supports.

The filter is a set of conditions, one per field. For example, the condition "severity": {"in": ["HIGH", "CRITICAL"]} matches alerts with HIGH or CRITICAL severity.

The following rules apply to both endpoints:

  • Combining conditions: All conditions you send must be true (implicit AND). There is no way to combine them with and or or.

  • Several operators in one condition: All of them must be true. For example, onOrAfter and before together match a time range.

  • Empty filter: An empty or absent filter matches everything.

  • Unsupported input: Anything the filter does not support, such as an unknown field or an operator a field does not offer, is silently ignored.

  • Empty lists: An in with an empty list matches nothing. A notIn with an empty list excludes nothing.

  • List size: A list operator accepts at most 1000 values. Longer lists are rejected with 400 Bad Request.

Filter alerts

List alerts matching a complex filter passed in the request body. The endpoint only reads data; POST is used so that the filter can be passed in the body. Pagination and sorting work the same as in List alerts (after, size, and sort query parameters), and the shared Filter rules apply.

You can filter by the following fields:

Field Filters by

status, severity, resolution

The alert field of the same name, using the operators equals, notEquals, in, and notIn. Values are matched literally.

findingType

Alerts with at least one finding of the given type. Only the operators equals and in are supported.

A type also matches all its subtypes, so equals is not an exact match (see Finding types).

affectedAssetUrn

Alerts whose findings affect the given asset, using the operators equals, notEquals, in, and notIn over URNs.

createdAt

When the alert was created, using the range operators after, onOrAfter, before, and onOrBefore.

The onOr variants include the boundary instant; after and before exclude it. Combine a lower and an upper bound to form a range, for example, onOrAfter with before.
Request: Filter alerts by severity, resolution, creation date, and affected asset
curl -X POST "https://{your-environment}.ataccama.one/api/data-observability/v1/alerts/filter" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "severity": {
        "in": ["HIGH", "CRITICAL"]
      },
      "resolution": {
        "in": ["NOT_SET", "OPEN", "EXPECTED"]
      },
      "createdAt": {
        "onOrAfter": "2026-07-01T00:00:00Z"
      },
      "affectedAssetUrn": {
        "equals": "urn:ata:{your-tenant}:catalog:catalog-item:8e106021-3655-463a-8884-6c7c6c315548"
      }
    }
  }'

The response has the same structure as in List alerts.

Retrieve an alert

Get the details of a specific alert, including the URNs of its findings. URL-encode the alert URN when placing it in the request path. Each colon (:) becomes %3A.

Request: Retrieve an alert
curl -X GET "https://{your-environment}.ataccama.one/api/data-observability/v1/alerts/{alertUrn}" \
  -H "Authorization: Bearer {access_token}"
Response: Alert with the URNs of its findings
{
  "urn": "urn:ata:{your-tenant}:data-observability:alert:0197f3a0-1111-7c0c-8f9d-3a2b4c5d6e7f",
  "status": "ACTIVE",
  "severity": "CRITICAL",
  "resolution": "OPEN",
  "createdAt": "2026-07-09T06:15:00Z",
  "updatedAt": "2026-07-10T05:40:00Z",
  "findingUrns": [
    "urn:ata:{your-tenant}:data-observability:finding:0197f3a0-2222-7c0c-8f9d-3a2b4c5d6e7f",
    "urn:ata:{your-tenant}:data-observability:finding:0197f3a0-4444-7c0c-8f9d-3a2b4c5d6e7f"
  ]
}

If an alert groups more than 1000 findings, the findingUrns list is truncated. To get the findings with their attributes, and with pagination, list them with the alertUrn parameter instead (see List findings).

List findings

List the findings in your environment.

To list the findings of one alert, use the alertUrn parameter. To restrict the result by finding type or status, use the corresponding query parameters. Each parameter accepts a single value. For multi-value or negated conditions, or to filter by affected asset, use Filter findings instead.

Request: List the findings of an alert
curl -X GET "https://{your-environment}.ataccama.one/api/data-observability/v1/findings?alertUrn={alertUrn}" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

alertUrn

string

No

Restricts the result to findings attached to the given alert.

findingType

string

No

Restricts the result to findings of the given type, including its subtypes (see Finding types).

status

string

No

Restricts the result to findings with the given status (ACTIVE, STALE, or INACTIVE).

size

integer

No

Number of findings to return per page.

Default: 20.

Max: 100.

sort

string

No

Field to sort by; prefix with a hyphen (-) for descending order. Only createdAt is supported, and only one field per request.

Default: -createdAt (newest first).

after

string

No

Cursor for forward pagination. Use the value from meta.next in the previous response.
Response: Alert findings
{
  "meta": {
    "total": 1
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:data-observability:finding:0197f3a0-2222-7c0c-8f9d-3a2b4c5d6e7f",
      "alertUrn": "urn:ata:{your-tenant}:data-observability:alert:0197f3a0-1111-7c0c-8f9d-3a2b4c5d6e7f",
      "findingType": "data.dq.threshold-breach-rule",
      "severity": "CRITICAL",
      "status": "ACTIVE",
      "summary": "Completeness on customer.email dropped to 71% (threshold 95%).",
      "affectedAssetUrn": "urn:ata:{your-tenant}:catalog:catalog-item:8e106021-3655-463a-8884-6c7c6c315548",
      "firstSeenAt": "2026-07-09T06:15:00Z",
      "lastSeenAt": "2026-07-10T05:40:00Z",
      "createdAt": "2026-07-09T06:15:04Z"
    }
  ]
}

The response is paginated the same way as in List alerts. For the meaning of each field, see Finding fields.

Filter findings

List findings matching a complex filter passed in the request body. The endpoint works the same way as Filter alerts. It only reads data, and the same pagination, sorting, and Filter rules apply.

You can filter by the following fields:

Field Filters by

alertUrn

The alert the finding belongs to, using the operators equals, notEquals, in, and notIn over URNs.

findingType

The finding type. Only the operators equals and in are supported.

A type also matches all its subtypes, so equals is not an exact match (see Finding types).

status

The finding status, using the operators equals, notEquals, in, and notIn.

affectedAssetUrn

The affected asset, using the operators equals, notEquals, in, and notIn over URNs.

Unlike the alert filter, there are no severity or date fields.

Request: Filter findings by type and status
curl -X POST "https://{your-environment}.ataccama.one/api/data-observability/v1/findings/filter" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "findingType": {
        "in": ["job.failure", "data.da.freshness"]
      },
      "status": {
        "equals": "ACTIVE"
      },
      "alertUrn": {
        "equals": "urn:ata:{your-tenant}:data-observability:alert:0197f3a0-1111-7c0c-8f9d-3a2b4c5d6e7f"
      }
    }
  }'

The response has the same structure as in List findings.

Retrieve a finding

Get the details of a specific finding. URL-encode the finding URN when placing it in the request path. Each colon (:) becomes %3A.

Request: Retrieve a finding
curl -X GET "https://{your-environment}.ataccama.one/api/data-observability/v1/findings/{findingUrn}" \
  -H "Authorization: Bearer {access_token}"
Response: Requested finding
{
  "urn": "urn:ata:{your-tenant}:data-observability:finding:0197f3a0-2222-7c0c-8f9d-3a2b4c5d6e7f",
  "alertUrn": "urn:ata:{your-tenant}:data-observability:alert:0197f3a0-1111-7c0c-8f9d-3a2b4c5d6e7f",
  "findingType": "data.dq.threshold-breach-rule",
  "severity": "CRITICAL",
  "status": "ACTIVE",
  "summary": "Completeness on customer.email dropped to 71% (threshold 95%).",
  "affectedAssetUrn": "urn:ata:{your-tenant}:catalog:catalog-item:8e106021-3655-463a-8884-6c7c6c315548",
  "firstSeenAt": "2026-07-09T06:15:00Z",
  "lastSeenAt": "2026-07-10T05:40:00Z",
  "createdAt": "2026-07-09T06:15:04Z"
}

For the meaning of each field, see Finding fields.

Drill down from an alert to the affected assets

To investigate an alert down to the assets behind it:

  1. List the alerts that need attention, for example, all active alerts (see List alerts).

  2. From the response, copy the URN of the alert you want to investigate.

  3. List the findings of the alert, passing its URN in the alertUrn parameter (see List findings).

  4. In each finding, check summary to see the problem and affectedAssetUrn to see which asset it affects.

  5. Get the details of the affected asset. For a catalog item, see Catalog Items API. For a pipeline job or dataset, see Pipeline Monitoring API.

Poll for new alerts and changes

The API does not push alerts to external systems. To keep another tool in sync, poll the API on a schedule.

To get notified about alerts without polling, set up notification policies in the web application. To track alerts as tickets in Jira or ServiceNow, see Escalate Alerts.

Retrieve new alerts

To retrieve the alerts created since your previous polling run:

  1. Call Filter alerts with createdAt.onOrAfter set to the newest createdAt value in your system. Sort the results oldest first (sort=createdAt).

    On the first polling run, send the request without a filter to retrieve all alerts.

  2. Page through the results with the after cursor until the response no longer contains meta.next.

  3. Save the results in your system, skipping the alerts that are already stored.

    The skip is needed because onOrAfter also matches alerts created exactly at the timestamp in your filter. Each polling run therefore returns the newest saved alert one more time.

Request: List alerts created since the previous polling run
curl -X POST "https://{your-environment}.ataccama.one/api/data-observability/v1/alerts/filter?sort=createdAt" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "createdAt": {
        "onOrAfter": "2026-08-26T06:00:00Z"
      }
    }
  }'

Detect changes to retrieved alerts

Alerts continue to change after you retrieve them. They can gain new findings, the status can change as the findings end, and your team can set a resolution at any time, even after the alert has ended.

To pick up these changes:

  1. Call Filter alerts with createdAt.onOrAfter set to the createdAt of the oldest alert you still track.

  2. Page through the results the same way as when retrieving new alerts.

  3. Compare each returned alert with your stored copy. A difference in any field, such as status, resolution, or updatedAt, means the alert changed.

The updatedAt timestamp alone is not a reliable way to find the changes. It is not possible to filter by updatedAt, and the timestamp does not reflect resolution changes (see Alert fields).

If you track only a few specific alerts, retrieve them individually instead (see Retrieve an alert).

Polling frequency

The API currently enforces no rate limits. To be ready for limits introduced later, handle 429 Too Many Requests and wait for the number of seconds specified in the Retry-After header before retrying.

The right polling frequency depends on your use case. For example, to retrieve alerts for reporting, polling a few times per day can be enough. Whichever frequency you choose, stay within the following maximums:

  • Retrieving new alerts (see Retrieve new alerts): Do not poll more often than about once per minute.

  • Detecting changes (see Detect changes to retrieved alerts): This check retrieves all the alerts you track again, in pages. Run it less frequently than the polling for new alerts, and not more often than about once per hour.

Error handling

The API returns standard HTTP status codes and reports errors as problem details (RFC 9457).

Error responses use the application/problem+json content type instead of application/json. The body contains the following fields:

  • type: A machine-readable error code, as listed in the following table.

  • title: A short summary of the problem type.

  • detail: An explanation of the specific problem.

The only exception is 401 Unauthorized, which does not use the problem details format.

Status code Error code Description

200 OK

—

Request successful.

400 Bad Request

VALIDATION_ERROR

Invalid request parameters or body (for example, a malformed URN or a filter list with more than 1000 values).

401 Unauthorized

—

Invalid or expired access token. Unlike the other error responses, the body does not use the problem details format. It is a plain JSON object or empty.

403 Forbidden

FORBIDDEN

Insufficient permissions to access the requested resource.

404 Not Found

RESOURCE_NOT_FOUND

Alert or finding does not exist. Returned by the retrieve endpoints only.

500 Internal Server Error

INTERNAL_ERROR

Unexpected server error. Try the request again later.

API reference

For detailed API reference, including all endpoints, parameters, request and response schemas, and examples, see Data Observability API specification.

Next steps

Was this page useful?