Data Quality 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.

The Data Quality API allows you to programmatically manage data quality monitoring, execute quality checks, and retrieve quality results for catalog items in Ataccama ONE.

Before using the Data Quality API, configure authentication as described in API Authentication.

API base URL

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

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

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

DQ monitors

Data quality monitors define the rules and configuration for evaluating data quality on catalog items.

List DQ monitors

Retrieve all DQ monitors configured for a specific catalog item.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`catalogItemUrn`	string	Yes	URN of the catalog item. For example: `urn:ata:{your-tenant}:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000`.

Query parameters
Parameter	Type	Required	Description
`after`	string	No	Cursor for forward pagination.
`before`	string	No	Cursor for backward pagination.
`size`	integer	No	Number of monitors to return. Default: `20`. Max: `100`.

Response example

{
  "meta": {
    "prev": null,
    "next": "cursor_string",
    "total": 5
  },
  "data": [
    {
      "urn": "urn:ata:acme-corp:data-quality:dq-monitor:123e4567-e89b-12d3-a456-426614174000",
      "name": "Primary Monitor",
      "status": "PUBLISHED",
      "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Get a DQ monitor

Retrieve detailed information about a specific DQ monitor or the primary monitor for a catalog item.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`catalogItemUrn`	string	Yes	URN of the catalog item.
`dqMonitorUrn`	string	Yes	URN of the DQ monitor, or `primary` to get the primary monitor. Example: `urn:ata:{your-tenant}:data-quality:dq-monitor:123e4567-e89b-12d3-a456-426614174000` or `primary`.

Use primary as the DQ monitor URN to access the default quality monitor for a catalog item without having to know its specific URN.

Request example

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/primary" \
  -H "Authorization: Bearer {access_token}"

Response example

{
  "urn": "urn:ata:acme-corp:data-quality:dq-monitor:123e4567-e89b-12d3-a456-426614174000",
  "name": "Primary Monitor",
  "status": "PUBLISHED",
  "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000",
  "manualRuleInstances": [],
  "termRuleInstances": [],
  "schedule": {
    "type": "DAILY",
    "time": "02:00:00"
  },
  "profilingConfiguration": {},
  "anomalyDetectionConfiguration": {}
}

Execute a DQ monitor

Trigger an on-demand execution of a DQ monitor to evaluate data quality.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/execute" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`catalogItemUrn`	string	Yes	URN of the catalog item.
`dqMonitorUrn`	string	Yes	URN of the DQ monitor, or `primary`.

Response example

{
  "processingUrn": "urn:ata:acme-corp:data-quality:processing:123e4567-e89b-12d3-a456-426614174000"
}

The response includes a processingUrn that you can use to track the execution status and retrieve results.

DQ processings

Processings represent individual executions of DQ monitors. Each time a DQ monitor runs (scheduled or on-demand), it creates a new processing record.

List processings

Retrieve execution history for a DQ monitor.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`catalogItemUrn`	string	Yes	URN of the catalog item.
`dqMonitorUrn`	string	Yes	URN of the DQ monitor, or `primary`.

Query parameters
Parameter	Type	Required	Description
`after`	string	No	Cursor for forward pagination.
`before`	string	No	Cursor for backward pagination.
`size`	integer	No	Number of processings to return. Default: `20`. Max: `100`.
`sort`	string	No	Sort order for results. Default: `-finishedAt` (most recent first). Prefix with a hyphen (`-`) for descending order.
`from`	string (date-time)	No	Start of the filtered time range (ISO 8601).
`to`	string (date-time)	No	End of the filtered time range (ISO 8601).
`state`	string	No	Filter by processing state (for example, `COMPLETED`, `FAILED`, `RUNNING`).

Response example

{
  "meta": {
    "prev": null,
    "next": "cursor_string",
    "total": 10
  },
  "data": [
    {
      "processingUrn": "urn:ata:acme-corp:data-quality:processing:123e4567-e89b-12d3-a456-426614174000",
      "startedAt": "2025-01-15T09:30:00Z",
      "finishedAt": "2025-01-15T10:00:00Z",
      "dqMonitorUrn": "urn:ata:acme-corp:data-quality:dq-monitor:123e4567-e89b-12d3-a456-426614174000",
      "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000",
      "processingState": "COMPLETED"
    }
  ]
}

Example: Filter processings by date range

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/primary/processings?from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&sort=-finishedAt" \
  -H "Authorization: Bearer {access_token}"

DQ results

DQ results contain the quality evaluation outcomes for a specific processing execution.

Get DQ results

Retrieve data quality results for a specific processing execution.

Catalog item attributes in the DQ results correspond to the version valid when the processing started.

If the catalog item structure has changed since the processing started, the attribute references might differ from the current catalog item structure.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings/{processingUrn}/dq-results" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`catalogItemUrn`	string	Yes	URN of the catalog item.
`dqMonitorUrn`	string	Yes	URN of the DQ monitor, or `primary`.
`processingUrn`	string	Yes	URN of the processing, or `latest` to get the most recent results. Example: `urn:ata:{your-tenant}:data-quality:processing:123e4567-e89b-12d3-a456-426614174000` or `latest`.

Query parameters
Parameter	Type	Required	Description
`attributeUrns`	array of strings	No	Specific catalog attribute URNs to retrieve attribute-level results.

Use latest as the processing URN to always get the most recent quality results without tracking processing URNs.

Example:

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/primary/processings/latest/dq-results" \
  -H "Authorization: Bearer {access_token}"

Response example

{
  "processingUrn": "urn:ata:acme-corp:data-quality:processing:123e4567-e89b-12d3-a456-426614174000",
  "overallQuality": {
    "passedCount": 95,
    "failedCount": 5
  },
  "processingDimensionResults": [
    {
      "dimension": {
        "urn": "urn:ata:acme-corp:data-quality:dimension:completeness",
        "name": "Completeness",
        "color": "#00FF00",
        "order": 1
      },
      "passedCount": 50,
      "failedCount": 2,
      "ruleInstanceCount": 52
    },
    {
      "dimension": {
        "urn": "urn:ata:acme-corp:data-quality:dimension:validity",
        "name": "Validity",
        "color": "#0000FF",
        "order": 2
      },
      "passedCount": 45,
      "failedCount": 3,
      "ruleInstanceCount": 48
    }
  ],
  "ruleInstanceProcessingResults": [
    {
      "ruleInstanceUrn": "urn:ata:acme-corp:data-quality:rule-instance:123e4567-e89b-12d3-a456-426614174000",
      "ruleUrn": "urn:ata:acme-corp:data-quality:rule:null-check",
      "ruleInstanceName": "Check Nulls in Email",
      "ruleName": "Null Check",
      "results": [
        {
          "passed": true,
          "recordCount": 1000
        }
      ]
    }
  ]
}

Get DQ results in bulk

Retrieve the latest DQ results for multiple catalog items in a single request.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-results/bulk" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": [
      {
        "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000",
        "dqMonitorUrn": "urn:ata:acme-corp:data-quality:dq-monitor:123e4567-e89b-12d3-a456-426614174000"
      },
      {
        "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:223e4567-e89b-12d3-a456-426614174000",
        "dqMonitorUrn": "urn:ata:acme-corp:data-quality:dq-monitor:223e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }'

Request constraints
Constraint	Description
Min items	1 catalog item/monitor pair required
Max items	100 pairs per request

Response example

[
  {
    "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000",
    "dqMonitorUrn": "urn:ata:acme-corp:data-quality:dq-monitor:123e4567-e89b-12d3-a456-426614174000",
    "processingUrn": "urn:ata:acme-corp:data-quality:processing:123e4567-e89b-12d3-a456-426614174000",
    "overallQuality": {
      "passedCount": 95,
      "failedCount": 5
    },
    "processingDimensionResults": []
  },
  {
    "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:223e4567-e89b-12d3-a456-426614174000",
    "dqMonitorUrn": "urn:ata:acme-corp:data-quality:dq-monitor:223e4567-e89b-12d3-a456-426614174000",
    "processingUrn": "urn:ata:acme-corp:data-quality:processing:223e4567-e89b-12d3-a456-426614174000",
    "overallQuality": {
      "passedCount": 180,
      "failedCount": 20
    },
    "processingDimensionResults": []
  }
]

Invalid samples

Invalid samples are records that failed data quality checks. You can retrieve these samples to investigate and fix data quality issues.

Get invalid sample headers

Retrieve the column headers for invalid samples before fetching the actual data.

Catalog item attributes in the DQ results correspond to the version valid when the processing started.

If the catalog item structure has changed since the processing started, the attribute references might differ from the current catalog item structure.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings/{processingUrn}/invalid-samples/headers" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`catalogItemUrn`	string	Yes	URN of the catalog item.
`dqMonitorUrn`	string	Yes	URN of the DQ monitor, or `primary`.
`processingUrn`	string	Yes	URN of the processing, or `latest`.

Response example

{
  "headers": [
    {
      "attributeUrn": "urn:ata:acme-corp:catalog:catalog-attribute:attr-001",
      "name": "customer_id",
      "columnType": "integer"
    },
    {
      "attributeUrn": "urn:ata:acme-corp:catalog:catalog-attribute:attr-002",
      "name": "email",
      "columnType": "varchar"
    },
    {
      "attributeUrn": "urn:ata:acme-corp:catalog:catalog-attribute:attr-003",
      "name": "registration_date",
      "columnType": "date"
    }
  ]
}

Get invalid samples

Retrieve the actual invalid sample records.

Catalog item attributes in the DQ results correspond to the version valid when the processing started.

If the catalog item structure has changed since the processing started, the attribute references might differ from the current catalog item structure.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings/{processingUrn}/invalid-samples" \
  -H "Authorization: Bearer {access_token}"

Query parameters
Parameter	Type	Required	Description
`after`	string	No	Cursor for forward pagination.
`before`	string	No	Cursor for backward pagination.
`size`	integer	No	Number of invalid samples to return. Default: `20`. Max: `100`.

Response example

{
  "meta": {
    "prev": null,
    "next": "cursor_string",
    "total": 15
  },
  "data": [
    {
      "recordId": 1001,
      "values": ["12345", "invalid-email", "2025-01-15"],
      "invalidRuleInstances": [
        {
          "ruleInstanceUrn": "urn:ata:acme-corp:data-quality:rule-instance:email-validation",
          "ruleInstanceName": "Email Format Check"
        }
      ]
    },
    {
      "recordId": 1002,
      "values": ["12346", null, "2025-01-16"],
      "invalidRuleInstances": [
        {
          "ruleInstanceUrn": "urn:ata:acme-corp:data-quality:rule-instance:email-null-check",
          "ruleInstanceName": "Email Not Null"
        }
      ]
    }
  ]
}

Complete example: Execute DQ and retrieve results

Here’s a complete workflow for executing data quality checks and retrieving results:

#!/bin/bash

# Configuration
ENVIRONMENT="your-environment"
REALM="your-realm"
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
CATALOG_ITEM_URN="urn:ata:your-tenant:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000"

BASE_URL="https://${ENVIRONMENT}.ataccama.one"
AUTH_URL="${BASE_URL}/auth/realms/${REALM}/protocol/openid-connect/token"
API_URL="${BASE_URL}/api/data-quality/v1"

# 1. Obtain access token
echo "Obtaining access token..."
TOKEN=$(curl -s -X POST "$AUTH_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  | jq -r '.access_token')

# 2. Execute DQ monitor
echo "Executing DQ monitor..."
PROCESSING_RESPONSE=$(curl -s -X POST "${API_URL}/catalog-items/${CATALOG_ITEM_URN}/dq-monitors/primary/execute" \
  -H "Authorization: Bearer $TOKEN")

PROCESSING_URN=$(echo "$PROCESSING_RESPONSE" | jq -r '.processingUrn')
echo "Processing started: $PROCESSING_URN"

# 3. Wait for processing to complete (poll every 10 seconds)
echo "Waiting for processing to complete..."
while true; do
  sleep 10
  PROCESSINGS=$(curl -s -X GET "${API_URL}/catalog-items/${CATALOG_ITEM_URN}/dq-monitors/primary/processings?size=1&sort=-finishedAt" \
    -H "Authorization: Bearer $TOKEN")

  STATE=$(echo "$PROCESSINGS" | jq -r '.data[0].processingState')

  if [ "$STATE" == "COMPLETED" ] || [ "$STATE" == "FAILED" ]; then
    echo "Processing $STATE"
    break
  fi
  echo "Processing status: $STATE"
done

# 4. Get DQ results
echo "Retrieving DQ results..."
curl -s -X GET "${API_URL}/catalog-items/${CATALOG_ITEM_URN}/dq-monitors/primary/processings/latest/dq-results" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 5. Get invalid sample headers
echo "Retrieving invalid sample headers..."
curl -s -X GET "${API_URL}/catalog-items/${CATALOG_ITEM_URN}/dq-monitors/primary/processings/latest/invalid-samples/headers" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 6. Get invalid samples
echo "Retrieving invalid samples..."
curl -s -X GET "${API_URL}/catalog-items/${CATALOG_ITEM_URN}/dq-monitors/primary/processings/latest/invalid-samples?size=10" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

echo "Data quality check complete!"

Example: Monitor multiple catalog items

Check data quality across multiple catalog items:

# Get bulk DQ results for multiple catalog items
curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-results/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": [
      {
        "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:item-001",
        "dqMonitorUrn": "urn:ata:acme-corp:data-quality:dq-monitor:monitor-001"
      },
      {
        "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:item-002",
        "dqMonitorUrn": "urn:ata:acme-corp:data-quality:dq-monitor:monitor-002"
      },
      {
        "catalogItemUrn": "urn:ata:acme-corp:catalog:catalog-item:item-003",
        "dqMonitorUrn": "urn:ata:acme-corp:data-quality:dq-monitor:monitor-003"
      }
    ]
  }' | jq '.[] | {catalogItemUrn, overallQuality}'

Error handling

The API returns standard HTTP status codes and problem details for errors:

Status code Description

Status code	Description
`200 OK`	Request successful.
`400 Bad Request`	Invalid request parameters or body.
`404 Not Found`	Catalog item, DQ monitor, or processing not found.
`500 Internal Server Error`	Server error during DQ execution.

200 OK

Request successful.

400 Bad Request

Invalid request parameters or body.

404 Not Found

Catalog item, DQ monitor, or processing not found.

500 Internal Server Error

Server error during DQ execution.

Error response example

{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Processing with URN 'urn:ata:your-tenant:data-quality:processing:invalid-id' was not found"
}

Best practices

Use the primary monitor: Access primary DQ monitors without tracking specific URNs.
Use latest results: Retrieve the most recent results with latest instead of specific processing URNs.
Poll for completion: When executing DQ monitors, poll the processings endpoint to check completion status.
Bulk operations for dashboards: Use bulk results endpoint when building dashboards that display quality across multiple catalog items.
Filter by date range: Use time-range filters when analyzing quality trends over time.
Paginate invalid samples: Process invalid samples in batches using pagination for large result sets.

Next steps

Learn about managing catalog items to set up data assets for quality monitoring.
Download the Data Quality API OpenAPI specification for detailed API reference.

Was this page useful?