Managing Data Quality issues in Management API¶

This guide explains how to work with the issues that Data Quality monitors find in your data through the Management 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 through Management API 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:

`type`	Monitor
`row-duplicates`	Duplication monitor
`volumes`	Volume monitor
`timeliness`	Timeliness monitor
`schema_consistency`	Column consistency monitor
`values`	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, Management 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, Management API returns HTTP 400 and 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:

Parameter	Description
`workspace_scope`	`ancestors`, `descendants`, or `family`: only the issues in the workspace given by `scope_from_workspace_id` and the workspaces above it, below it, or both. The result never includes workspaces the key cannot see.
`scope_from_workspace_id`	The workspace UUID that `workspace_scope` starts from. Required when the instance has more than one top-level workspace; otherwise it defaults to the top-level workspace. Without `workspace_scope`, this parameter has no effect and the request covers every workspace the key can see.

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 Authorization with value Bearer {{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.

Parameter	Description
`workspace_scope`, `scope_from_workspace_id`	Only the issues of the selected workspaces. For more information, see Selecting workspaces.
`datastream_id`	Only the issues of these datastream UUIDs. Repeat the parameter for several values, up to 50.
`monitor_id`	Only the issues of these custom monitor UUIDs. Repeat the parameter for several values, up to 50.
`type`	Only the issues of one type: `row-duplicates`, `values`, `volumes`, `timeliness`, or `schema_consistency`.
`severity`	`error` or `warning`.
`is_acknowledged`	`true` for acknowledged issues only, `false` for unacknowledged issues only.
`date_from`	Only the issues whose fetch started on this day or later, as `YYYY-MM-DD` (UTC).
`date_to`	Only the issues whose fetch started on this day or earlier, as `YYYY-MM-DD` (UTC). `date_from` after `date_to` returns HTTP `400`.
`page`	The page number, starting at `1`. Default: `1`.
`page_size`	The number of items per page. Default: `50`. Values above `100` return `100` items.

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:

Field	Description
`id`	The numeric ID of the issue.
`type`	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.
`severity`	`error` or `warning`.
`start`	When the fetch that raised the issue started.
`is_acknowledged`	`true` if the issue is acknowledged.
`expected`	Whether the issue was marked as expected. `null` until someone marks it. Only the issues of universal monitors use this field.
`violations`	The number of violations the monitor found.
`message`	The issue message.
`data_source`	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.
`job_group_id`	The job group whose fetch raised the issue. `null` if the issue is not tied to a job group. For a timeliness or column consistency issue, this is the job group the issue recorded itself, which can differ from the job of the issue’s log entry. The job group requests select issues by the job of their log entry, so they can leave out such an issue, for example a timeliness issue recorded without a fetch job. To change such an issue, use its ID.
`datastream`	The `id`, `name`, and `workspace` of the datastream.
`monitor`	The `id` and `name` of the custom monitor that raised the issue. `null` for universal monitors.
`extract_id`	The data extract the issue was found on. `null` if the data extract was deleted.

Each type adds the following fields:

`type`	Additional fields
`values`	`detailed_type`: `missing-field` or `rule-violated`.
`row-duplicates`	None.
`volumes`	`anomaly_type` (`spike`, `drop`, or `drop_to_zero`), `deviation`, and `row_count`.
`timeliness`	`expected_delivery`, `schedule`, `schedule_type`, `smart_schedule`, and `cause` (`stopped_by_error` or `task_not_finished`).
`schema_consistency`	`issue_types` (`missing_columns`, `new_columns`, or `order_mismatch`) and `auto_restored`.

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 the id of the issue.
In the HTTP request header, include the parameter Authorization with value Bearer {{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:

`type`	Details
`values`	`names`: the fields missing from the data extract, for a `missing-field` issue. `rule_violations`: for a `rule-violated` issue, one summary per violated rule block, with the block’s `rule_key`, the number of `violations`, the number of `distinct_rows` recorded up to the row limit, `has_target_columns`, and `rows_truncated` and `columns_truncated`, which are `true` if the monitor found more rows or columns for that block than it recorded.
`row-duplicates`	`columns` and `columns_mode`: the columns the monitor compared. `duplicated_rows`: the number of distinct duplicated rows recorded, up to the row limit. `rows_truncated` and `columns_truncated` are `true` if the monitor found more rows or columns than it recorded.
`volumes`	`datapoints`: the last 50 fetches the monitor compared, each with its `volume`, the fetch range, the expected range `lower_bound` to `upper_bound`, and `is_outlier`.
`timeliness`	`due_date`: when the data was due. `extraction_log_message`: the message of the log entry that delayed the fetch. `null` if there is none or the key cannot see it.
`schema_consistency`	`extract_schema`: the columns of the data extract. `baseline_schema`: the columns of the baseline. `diff`: the differences between them. `issue_types_count`: the number of missing columns, new columns, and columns in a different order.

If the issue does not exist or the key cannot see it, Management 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 the extract_id of 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 the job_group_id of an issue. A timeliness or column consistency issue can carry a job_group_id and still not be listed here. For more information, see the job_group_id field in Listing issues.
In the HTTP request header, include the parameter Authorization with value Bearer {{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, Management 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¶

The following requests summarize issues across datastreams. All of them accept the parameters described in Selecting workspaces.

Request	Parameters	What it returns
`GET https://{{INSTANCE}}/api/v1/monitors/issues/analytics/top-datastreams/`	`type` (required): the issue type. `limit`: the number of datastreams, from `1` to `30`. Default: `5`.	The datastreams with the most unacknowledged issues of this type, most issues first. Each item contains the `datastream` (`id` and `name`) and its number of `errors` and `warnings`.
`GET https://{{INSTANCE}}/api/v1/monitors/issues/analytics/daily/`	`date_from` and `date_to` (required, `YYYY-MM-DD`): the period. `date_to` can be at most 366 days after `date_from`; a longer range returns HTTP `400`. Optionally, the `datastream_id`, `monitor_id`, `type`, `severity`, and `is_acknowledged` filters described in Listing issues.	One item for each day with issues, newest day first. Each item contains the `date`, the number of unacknowledged `errors` and `warnings`, and the number of `acknowledged` issues. When you filter by `severity` or `is_acknowledged`, the counts that do not match the filter are `0`.
`GET https://{{INSTANCE}}/api/v1/monitors/issues/analytics/totals/`	`type` (required): the issue type.	The number of monitored datastreams with unacknowledged issues of this type (`datastreams_with_issues`) and without them (`datastreams_without_issues`), the number of unacknowledged issues (`issues`), and the number of unacknowledged issues up to the end of yesterday in UTC (`issues_yesterday`). `is_active` is `false` if no monitor of this type watches any datastream.

A datastream counts as monitored when a universal monitor of the type is enabled for it, or, for the values type, when a custom monitor is assigned to it. datastreams scheduled for deletion are not counted.

The cURL request example is the following. It counts the issues of each day in October 2026:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/monitors/issues/analytics/daily/?date_from=2026-10-01&date_to=2026-10-31' \
--header 'Authorization: Bearer {{KEY}}'

Acknowledging and reopening issues¶

To acknowledge issues, or to reopen acknowledged issues, follow these steps:

Create a POST request to one of the following endpoints:

To acknowledge issues:

https://{{INSTANCE}}/api/v1/monitors/issues/acknowledge/

To reopen acknowledged issues:

https://{{INSTANCE}}/api/v1/monitors/issues/unacknowledge/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
Select the issues in one of the following ways:
- To select specific issues, in the HTTP request body, include issue_ids with a list of up to 50 issue IDs.
- To select every issue of one or more workspaces, add the workspace_scope and scope_from_workspace_id query parameters, and send an empty JSON object ({}) as the request body. For more information, see Selecting workspaces.
If you use both, only the listed issues in the selected workspaces change. If you use neither, Management API returns HTTP 400.
Send the request.

As a result, the selected issues are acknowledged or reopened. The response lists the issues that changed:

{
  "affected": {
    "issue_ids": [81234, 81240]
  }
}

Issues that the key cannot see, IDs that are not issues, and issues that are already acknowledged or open are left out of the response. Repeating the request returns an empty list.

The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/monitors/issues/acknowledge/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{"issue_ids": [81234, 81240]}'

To acknowledge every issue of one workspace and the workspaces below it, use the following cURL request:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/monitors/issues/acknowledge/?workspace_scope=descendants&scope_from_workspace_id={{WORKSPACE_ID}}' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{}'

Warning

If the selection would change more than 1000 issues, Management API returns HTTP 400 and no issue is changed. Narrow the selection, for example to a smaller workspace or to a job group.

Acknowledging and reopening the issues of a job group¶

To acknowledge or reopen the issues raised by the fetch of one job group, follow these steps:

Create a POST request to one of the following endpoints:
- To acknowledge issues:
```
https://{{INSTANCE}}/api/v1/monitors/issues/job-groups/{{JOB_GROUP_ID}}/acknowledge/
```
- To reopen acknowledged issues:
```
https://{{INSTANCE}}/api/v1/monitors/issues/job-groups/{{JOB_GROUP_ID}}/unacknowledge/
```
Replace {{JOB_GROUP_ID}} with the numeric ID of the job group, for example the job_group_id of an issue. See the note at the end of this section for issues that carry a job_group_id but are not selected.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include any of the following:
- issue_ids with a list of up to 50 issue IDs of the job group to select only these issues.
- exclude_issue_ids with a list of up to 50 issue IDs to leave out of the selection.
To select every issue of the job group, send an empty JSON object ({}).
Send the request.

As a result, the selected issues of the job group are acknowledged or reopened, and the response lists the issues that changed, as described in Acknowledging and reopening issues. A job group with more than 1000 issues to change returns HTTP 400; select the issues with issue_ids instead.

The cURL request example is the following. It acknowledges every issue of the job group except one:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/monitors/issues/job-groups/{{JOB_GROUP_ID}}/acknowledge/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{"exclude_issue_ids": [81240]}'

Note

The job group requests select issues by the job of their log entry. A timeliness or column consistency issue can record its own job_group_id that differs from that job, for example a timeliness issue recorded without a fetch job. Such an issue is not listed or changed by these requests even though its job_group_id names the job group. To change it, use its ID as described in Acknowledging and reopening issues.

Marking an issue as expected¶

You can record whether an issue of a universal monitor was expected, for example a volume drop during a planned campaign pause.

To mark an issue as expected, follow these steps:

Create a PUT request to the following endpoint:
```
https://{{INSTANCE}}/api/v1/monitors/issues/{{ISSUE_ID}}/expected/
```
Replace {{ISSUE_ID}} with the id of the issue.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include expected with value true if the issue was expected, or false if it was not.
Send the request.

As a result, the expected field of the issue is updated, and the response contains the issue.

The issues of custom monitors (type values) do not record this value: for them, Management API returns HTTP 400.

The cURL request example is the following:

curl --location --request PUT 'https://{{INSTANCE}}/api/v1/monitors/issues/{{ISSUE_ID}}/expected/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{"expected": true}'

Accepting a column structure change into the baseline¶

When the column consistency monitor reports an issue because the columns of a data extract changed on purpose, you can make the new column structure the baseline of the datastream. For more information on the baseline, see Updating the baseline of the column consistency monitor.

To accept the column structure of an issue into the baseline, follow these steps:

(Optional) Check the change. Read the details of the issue as described in Reading the details of an issue, and compare extract_schema with baseline_schema, or read diff.
Create a POST request to the following endpoint:
```
https://{{INSTANCE}}/api/v1/monitors/issues/{{ISSUE_ID}}/apply-schema/
```
Replace {{ISSUE_ID}} with the id of an issue of type schema_consistency.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.

As a result, the column structure of the issue’s data extract becomes the baseline of the datastream, and the issue is acknowledged. The response contains the new baseline: its schema_columns, when it was changed (updated), updated_by, which is the user the API key belongs to, and extract_id. Unlike the extract_id of an issue, this is the UUID of the data extract the issue was found on. It is null if that data extract was deleted or has no UUID.

Warning

The new baseline replaces the previous one, and the column consistency monitor checks all following fetches against it. To be able to return to the previous column structure, keep the issue’s baseline_schema (from its details) before you apply. To restore it, send that list of column names in a PUT request to https://{{INSTANCE}}/api/v1/monitors/universal/datastreams/{{DATASTREAM_UUID}}/baseline-schema/, or update the baseline in Adverity as described in Updating the baseline of the column consistency monitor.

Management API returns HTTP 404 if the issue does not exist, the key cannot see it, it is not of type schema_consistency, or the datastream has no baseline. It returns HTTP 400 if the issue did not record the columns of its data extract.

The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/monitors/issues/{{ISSUE_ID}}/apply-schema/' \
--header 'Authorization: Bearer {{KEY}}'

Previewing custom monitor rules on a data extract¶

Before you save a custom monitor, you can check its rules against the rows of a data extract to see which rows would violate them. The check saves nothing, so the rules do not need to belong to a monitor. For more information on the rules, see Working with custom monitors.

To preview custom monitor rules, follow these steps:

Create a POST request to the following endpoint:
```
https://{{INSTANCE}}/api/v1/monitors/preview/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.

In the HTTP request body, include the following parameters:

Parameter	Required	Description
`extract_id`	Yes	The numeric ID of the data extract whose rows to check.
`blocks`	Yes	The rule blocks to check, from 1 to 50. Each block has a `key` (UUID) of your choice and a `condition`, in the same form as the rule blocks of a custom monitor.
`has_target_columns`	No	`true` if the rules name the columns of the datastream’s schema instead of the source columns. Default: `false`.
`limit`	No	The number of rows to check, from the start of the data extract. From `1` to `1000`. Default: `100`.

Send the request.

As a result, you obtain one item for each rule block, with the block’s key and violated_rows: the positions of the checked rows that violate the block, counted from 0.

[
  {
    "key": "54cdeeb5-1db4-494b-97ee-a48c5af66874",
    "violated_rows": [0, 7, 42]
  }
]

If the data extract does not exist, the key cannot see it, or its data is no longer stored, Management API returns HTTP 404.

Tip

To find the columns and operators a rule can use, send GET requests to the following endpoints:

https://{{INSTANCE}}/api/v1/monitors/columns/?datastream_id={{DATASTREAM_UUID}} for the source columns.
https://{{INSTANCE}}/api/v1/monitors/target-columns/?datastream_id={{DATASTREAM_UUID}} for the schema columns, if has_target_columns is true.
https://{{INSTANCE}}/api/v1/monitors/operators/ for the operators of each column type.

The cURL request example is the following. It checks one rule block on the first 100 rows of a data extract:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/monitors/preview/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{"extract_id": {{EXTRACT_ID}}, "limit": 100, "blocks": [{"key": "54cdeeb5-1db4-494b-97ee-a48c5af66874", "representation": "date-format", "condition": {"key": "091610f9-52e1-44c1-92c0-514b453cdac2", "operation": "and", "conditions": [{"key": "9493426c-08da-413b-b449-00a0e32f6447", "operation": "or", "conditions": [{"key": "67122737-e878-4f2f-8479-222bf91417d2", "column": "Date", "columnType": 4, "operation": 16, "value": "2022-06-01"}]}]}}]}'

What’s next?¶

To assign custom monitors to datastreams, see Bulk assigning custom monitors in Management API.
To learn more about the monitors and their issues, see Working with universal monitors and Viewing details of the Data Quality issues.