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

Pipeline Monitoring 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 retrieve the orchestrator connections, pipeline jobs, and datasets that pipeline monitoring observes. The most common use is resolving the assets that data observability findings reference in affectedAssetUrn (see Monitor Data Observability Alerts via API).

The Pipeline Monitoring API is read-only. Pipeline jobs and datasets are recorded from observed run events (see Pipeline Monitoring). Orchestrator connections are managed in the web application (see Connect to an Orchestrator).

Prerequisites

Before using the Pipeline Monitoring 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 Pipeline Monitoring API endpoints are accessed through the following base URL:

https://{your-environment}.ataccama.one/api/pipeline-monitoring/v1

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

When to use this API

Use the Pipeline Monitoring API when you need to:

  • Investigate alert findings: Get the details of the pipeline job behind a job failure finding, or of the dataset behind a schema change finding (see Find the asset behind a finding).

  • Map observed datasets to catalog items: Follow the catalogItemUrns bridge from an observed dataset to its catalog items, or find the dataset observed for a given catalog item (see How datasets map to catalog items).

  • Inventory observed pipelines: List the connected orchestrators and the jobs observed from their run events.

Orchestrators, pipeline jobs, and datasets

Pipeline monitoring observes your pipelines through orchestrator run events (OpenLineage) and records three kinds of entities:

  • Orchestrator: A configured connection to a pipeline orchestrator, such as dbt or Airflow. Connection credentials are never exposed through the API. To connect an orchestrator, use the web application (see Connect to an Orchestrator).

  • Pipeline job: A job observed from orchestrator run events. Run history is not exposed.

  • Dataset: A physical data asset, such as a table, observed as an input or output of pipeline jobs.

How datasets map to catalog items

The same physical table can be represented in two ways in Ataccama ONE. It is recorded as a catalog item, once for each source it appears in. Pipeline monitoring observes it as a dataset from run events. Because a table can be cataloged in more than one source, a dataset can match more than one catalog item.

The dataset’s catalogItemUrns field lists the matched catalog items. This is also why data observability findings point to two different kinds of assets. DQ and freshness findings reference the catalog item, while schema change and observed-data findings reference the dataset.

Orchestrator fields

Field Description

urn

The URN of the orchestrator, in the format urn:ata:{tenant}:pipeline-monitoring:orchestrator:{uuid}.

name

The name of the orchestrator connection.

type

The orchestrator type, for example, DBT_WITH_OPEN_LINEAGE or AIRFLOW_WITH_OPEN_LINEAGE. The set is extensible. New values might be added over time, so make sure your integration handles unknown values gracefully.

createdAt

When the orchestrator connection was created.

Pipeline job fields

Field Description

urn

The URN of the pipeline job, in the format urn:ata:{tenant}:pipeline-monitoring:pipeline-job:{uuid}.

name

The fully qualified job name as observed (the OpenLineage job name), for example, analytics.nightly_customers. Within one orchestrator, the combination of name and namespace is unique.

namespace

The OpenLineage namespace of the job, for example, dbt or default. The namespace can be any value the orchestrator reports.

orchestratorUrn

The URN of the orchestrator the job was observed from.

Dataset fields

Field Description

urn

The URN of the dataset, in the format urn:ata:{tenant}:pipeline-monitoring:dataset:{uuid}.

name

The fully qualified dataset name as observed (the OpenLineage full name), for example, warehouse.public.customers. The combination of name and namespace is unique across all datasets.

namespace

The OpenLineage namespace of the dataset, which identifies the data store it lives in, for example, postgres://warehouse:5432.

dataStoreName

The name of the data store the dataset belongs to.

catalogItemUrns

The URNs of the catalog items matched to the dataset (see How datasets map to catalog items). The list is empty while the dataset is not matched to any catalog item. To get the details of a catalog item, see Catalog Items API.

createdAt

When the dataset was first recorded.

Find the asset behind a finding

To get the details of the asset behind a finding, use the endpoint that matches the resource type in the finding’s affectedAssetUrn:

List orchestrators

List the configured orchestrator connections.

Request: List orchestrators
curl -X GET "https://{your-environment}.ataccama.one/api/pipeline-monitoring/v1/orchestrators?size=20" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

size

integer

No

Number of orchestrators 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 orchestrators
{
  "meta": {
    "total": 1
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:pipeline-monitoring:orchestrator:0197f3a0-6666-7c0c-8f9d-3a2b4c5d6e7f",
      "name": "dbt production",
      "type": "DBT_WITH_OPEN_LINEAGE",
      "createdAt": "2026-05-02T09:00:00Z"
    }
  ]
}

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

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

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

Retrieve an orchestrator

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

Request: Retrieve an orchestrator
curl -X GET "https://{your-environment}.ataccama.one/api/pipeline-monitoring/v1/orchestrators/{orchestratorUrn}" \
  -H "Authorization: Bearer {access_token}"

The response returns the orchestrator with the fields described in Orchestrator fields.

List pipeline jobs

List the observed pipeline jobs. To list the jobs of a single orchestrator, use the orchestratorUrn parameter. Pipeline jobs are sorted by name, unlike the other list endpoints, which sort by createdAt.

Request: List the pipeline jobs of an orchestrator
curl -X GET "https://{your-environment}.ataccama.one/api/pipeline-monitoring/v1/pipeline-jobs?orchestratorUrn={orchestratorUrn}" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

orchestratorUrn

string

No

Restricts the result to jobs observed from the given orchestrator.

size

integer

No

Number of pipeline jobs to return per page.

Default: 20.

Max: 100.

sort

string

No

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

Default: name (ascending).

after

string

No

Cursor for forward pagination. Use the value from meta.next in the previous response.
Response: Page of pipeline jobs
{
  "meta": {
    "total": 2
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:pipeline-monitoring:pipeline-job:0197f3a0-8888-7c0c-8f9d-3a2b4c5d6e7f",
      "name": "analytics.hourly_orders",
      "namespace": "dbt",
      "orchestratorUrn": "urn:ata:{your-tenant}:pipeline-monitoring:orchestrator:0197f3a0-6666-7c0c-8f9d-3a2b4c5d6e7f"
    },
    {
      "urn": "urn:ata:{your-tenant}:pipeline-monitoring:pipeline-job:0197f3a0-5555-7c0c-8f9d-3a2b4c5d6e7f",
      "name": "analytics.nightly_customers",
      "namespace": "dbt",
      "orchestratorUrn": "urn:ata:{your-tenant}:pipeline-monitoring:orchestrator:0197f3a0-6666-7c0c-8f9d-3a2b4c5d6e7f"
    }
  ]
}

The response is paginated the same way as in List orchestrators. For the meaning of each field, see Pipeline job fields.

Retrieve a pipeline job

Get the details of a specific pipeline job, for example, the job referenced by a job failure finding’s affectedAssetUrn. URL-encode the pipeline job URN when placing it in the request path. Each colon (:) becomes %3A.

Request: Retrieve a pipeline job
curl -X GET "https://{your-environment}.ataccama.one/api/pipeline-monitoring/v1/pipeline-jobs/{pipelineJobUrn}" \
  -H "Authorization: Bearer {access_token}"

The response returns the pipeline job with the fields described in Pipeline job fields.

List datasets

List the observed datasets. To find the dataset matched to a catalog item, use the catalogItemUrn parameter. Each catalog item matches at most one dataset, so the response contains one dataset or none.

Request: Find the dataset matched to a catalog item
curl -X GET "https://{your-environment}.ataccama.one/api/pipeline-monitoring/v1/datasets?catalogItemUrn={catalogItemUrn}" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

catalogItemUrn

string

No

Restricts the result to the dataset matched to the given catalog item. The mapping is unique, so at most one dataset is returned.

size

integer

No

Number of datasets 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: Dataset matched to the catalog item
{
  "meta": {
    "total": 1
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:pipeline-monitoring:dataset:0197f3a0-7777-7c0c-8f9d-3a2b4c5d6e7f",
      "name": "warehouse.public.customers",
      "namespace": "postgres://warehouse:5432",
      "dataStoreName": "warehouse",
      "catalogItemUrns": [
        "urn:ata:{your-tenant}:catalog:catalog-item:8e106021-3655-463a-8884-6c7c6c315548"
      ],
      "createdAt": "2026-06-11T14:20:00Z"
    }
  ]
}

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

Retrieve a dataset

Get the details of a specific dataset, for example, the dataset referenced by a schema change finding’s affectedAssetUrn. URL-encode the dataset URN when placing it in the request path. Each colon (:) becomes %3A.

Request: Retrieve a dataset
curl -X GET "https://{your-environment}.ataccama.one/api/pipeline-monitoring/v1/datasets/{datasetUrn}" \
  -H "Authorization: Bearer {access_token}"

The response returns the dataset with the fields described in Dataset fields.

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 (for example, a malformed URN).

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

Orchestrator, pipeline job, or dataset 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 Pipeline Monitoring API specification.

Next steps

Was this page useful?