Managing Data Quality issues
On this page
This guide explains how to work with the issues that Data Quality monitors find in your data through the Connect API. You can do the following:
-
List and filter monitor issues, read the details of one issue, and view issue analytics.
-
Acknowledge and reopen issues, mark an issue as expected, and accept a changed column structure into the baseline.
-
Check the rules of a custom monitor against a data extract before you save the monitor.
This guide covers what is specific to Data Quality issues: their details, filters, analytics, and actions. The legacy issue list described in Listing issues returns all issues of your datastreams, including Data Quality issues, under the same ID.
The v1 endpoints follow their own conventions for authentication, identifiers, pagination, filters, and errors. For more information, see Working with v1 endpoints.
Introduction
What is a Data Quality issue?
An issue records that a monitor found a problem in a data extract of a datastream, for example duplicate rows, an unusual row count, a late fetch, a changed column structure, or values that break a rule of a custom monitor. For more information, see Viewing details of the Data Quality issues.
How are issues identified?
Each issue has a numeric id: the ID of the log entry that recorded the issue, the same ID that GET /api/errors/ shows. datastreams, monitors, and workspaces are identified by UUID, and data extracts and job groups by numeric ID.
Which issue types exist?
The type field of each issue names the monitor that found it:
Scroll horizontally to see the full table.
| Monitor |
|---|---|
| Duplication monitor |
| Volume monitor |
| Timeliness monitor |
| Column consistency monitor |
| Custom monitor |
Prerequisites
Before you complete the procedures in this guide, perform the following action:
-
Use a Connect API key with the following permissions:
-
Monitor: Read-only (
monitor:read) to list and read issues and to view issue analytics. -
Monitor: Write (
monitor:write) to acknowledge, reopen, and mark issues as expected, and to accept a changed column structure into the baseline. -
Monitor: Read-only (
monitor:read) and Datastream: Read-only (datastream:read) to check custom monitor rules against a data extract. The check reveals the values of the data extract, so it needs both permissions.
Picking Write for a permission also gives the key its Read-only access. Without the permission a request needs, Connect API returns HTTP
403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity. -
Limitations
-
A request that acknowledges or reopens issues can name at most 50 issue IDs. If it would change more than 1000 issues, Connect API returns HTTP
400and changes nothing. Narrow the selection with issue IDs, a workspace selection, or a job group. -
The details of an issue summarize the violations but do not contain the violating or duplicated rows themselves. To view these rows, use the Data Quality page in Adverity.
-
Issues in workspaces that are scheduled for deletion are not listed and cannot be changed.
Selecting workspaces
By default, the requests in this guide cover every issue the API key can see: the issues of the key’s workspace and the workspaces below it. To narrow a request to one part of your workspace tree, add the following query parameters:
Scroll horizontally to see the full table.
Parameter | Description |
|---|---|
|
|
| The workspace UUID that |
For example, workspace_scope=descendants&scope_from_workspace_id={{WORKSPACE_ID}} selects the issues of one workspace and the workspaces below it, as the Data Quality page of this workspace shows them.
These parameters work on the issue list, the issue analytics, and the requests that acknowledge or reopen issues by ID or by workspace. The requests for the issues of a job group do not accept them.
Listing issues
To list Data Quality issues, follow these steps:
-
Create a GET request to the following endpoint:
https://{{INSTANCE}}/api/v1/monitors/issues/ -
In the HTTP request header, include the parameter
Authorizationwith valueBearer {{KEY}}. -
(Optional) To filter the results, add any of the following query parameters. If you combine several parameters, the response contains only the issues that match all of them.
Scroll horizontally to see the full table.
Parameter
Description
workspace_scope,scope_from_workspace_idOnly the issues of the selected workspaces. For more information, see Selecting workspaces.
datastream_idOnly the issues of these datastream UUIDs. Repeat the parameter for several values, up to 50.
monitor_idOnly the issues of these custom monitor UUIDs. Repeat the parameter for several values, up to 50.
typeOnly the issues of one type:
row-duplicates,values,volumes,timeliness, orschema_consistency.severityerrororwarning.is_acknowledgedtruefor acknowledged issues only,falsefor unacknowledged issues only.date_fromOnly the issues whose fetch started on this day or later, as
YYYY-MM-DD(UTC).date_toOnly the issues whose fetch started on this day or earlier, as
YYYY-MM-DD(UTC).date_fromafterdate_toreturns HTTP400.pageThe page number, starting at
1. Default:1.page_sizeThe number of items per page. Default:
50. Values above100return100items. -
Send the request.
As a result, you obtain the issues, newest fetch first.
The cURL request example is the following. It lists the unacknowledged errors of one workspace and the workspaces below it:
curl --location --request GET 'https://{{INSTANCE}}/api/v1/monitors/issues/?workspace_scope=descendants&scope_from_workspace_id={{WORKSPACE_ID}}&severity=error&is_acknowledged=false' \
--header 'Authorization: Bearer {{KEY}}'
Example of JSON response (cropped to show one issue):
{
"items": [
{
"id": 81234,
"type": "values",
"detailed_type": "rule-violated",
"severity": "error",
"start": "2026-10-28T03:00:12Z",
"is_acknowledged": false,
"expected": null,
"violations": 12,
"message": "{{ISSUE_MESSAGE}}",
"data_source": "{{CONNECTOR_NAME}}",
"job_group_id": 5120,
"datastream": {
"id": "{{DATASTREAM_UUID}}",
"name": "{{DATASTREAM_NAME}}",
"workspace": {
"id": "{{WORKSPACE_UUID}}",
"name": "{{WORKSPACE_NAME}}"
}
},
"monitor": {
"id": "{{MONITOR_UUID}}",
"name": "{{MONITOR_NAME}}"
},
"extract_id": 51234
}
],
"count": 1
}
The following table describes the fields of each issue:
Scroll horizontally to see the full table.
Field | Description |
|---|---|
| The numeric ID of the issue. |
| The type of the issue. The fields after the common ones depend on the type. For more information, see Reading the details of an issue. |
|
|
| When the fetch that raised the issue started. |
|
|
| Whether the issue was marked as expected. |
| The number of violations the monitor found. |
| The issue message. |
| The name of the datastream’s connector, as Adverity displays it. This is a display name, not an identifier: it can change and is not unique. |
| The job group whose fetch raised the issue. |
| The |
| The |
| The data extract the issue was found on. |
Each type adds the following fields:
Scroll horizontally to see the full table.
| Additional fields |
|---|---|
|
|
| None. |
|
|
|
|
|
|
Reading the details of an issue
To read the details of one issue, follow these steps:
-
Create a GET request to the following endpoint:
https://{{INSTANCE}}/api/v1/monitors/issues/{{ISSUE_ID}}/Replace
{{ISSUE_ID}}with theidof the issue. -
In the HTTP request header, include the parameter
Authorizationwith valueBearer {{KEY}}. -
Send the request.
As a result, you obtain the issue with the fields described in Listing issues and the following details of its type:
Scroll horizontally to see the full table.
| Details |
|---|---|
|
|
|
|
|
|
|
|
|
|
If the issue does not exist or the key cannot see it, Connect API returns HTTP 404.
The cURL request example is the following:
curl --location --request GET 'https://{{INSTANCE}}/api/v1/monitors/issues/{{ISSUE_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'
Listing the issues of a data extract or a job group
To list the issues found on one data extract, or raised by the fetch of one job group, follow these steps:
-
Create a GET request to one of the following endpoints:
-
For a data extract:
https://{{INSTANCE}}/api/v1/monitors/issues/extracts/{{EXTRACT_ID}}/Replace
{{EXTRACT_ID}}with the numeric ID of the data extract, for example theextract_idof an issue. -
For a job group:
https://{{INSTANCE}}/api/v1/monitors/issues/job-groups/{{JOB_GROUP_ID}}/Replace
{{JOB_GROUP_ID}}with the numeric ID of the job group, for example thejob_group_idof an issue. A timeliness or column consistency issue can carry ajob_group_idand still not be listed here. For more information, see thejob_group_idfield in Listing issues.
-
-
In the HTTP request header, include the parameter
Authorizationwith valueBearer {{KEY}}. -
Send the request.
As a result, you obtain the issues of the data extract or the job group, paginated with the page and page_size query parameters. Each issue has the fields described in Listing issues.
For a data extract, the response also contains the issues found on copies of the same source data extract that the key can see.
If the data extract does not exist or the key cannot see it, Connect API returns HTTP 404. A job group that does not exist or that the key cannot see returns an empty list.
The cURL request example is the following:
curl --location --request GET 'https://{{INSTANCE}}/api/v1/monitors/issues/job-groups/{{JOB_GROUP_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'
Viewing issue analytics
For details, see Viewing issue analytics and previewing monitor rules.
Acknowledging and reopening issues
For details, see Acknowledging and reopening Data Quality issues.
Marking an issue as expected
For details, see Acknowledging and reopening Data Quality issues.
Accepting a column structure change into the baseline
For details, see Acknowledging and reopening Data Quality issues.
Previewing custom monitor rules on a data extract
For details, see Viewing issue analytics and previewing monitor rules.
What’s next?
-
To assign custom monitors to datastreams, see Bulk assigning custom monitors.
-
To learn more about the monitors and their issues, see Working with universal monitors and Viewing details of the Data Quality issues.