> For the complete documentation index, see [llms.txt](https://docs.decube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decube.io/public-api/overview/index/data-quality-v2.md).

# Data Quality V2

Manage Data Quality V2 monitors, run checks on demand, and work cases and incidents from your own pipelines and tools

The Data Quality V2 API gives you programmatic access to the monitors, runs, cases, and incidents you work with in the [Data Quality V2](https://docs.decube.io/data-quality-v2/overview.md) module. Use it to manage monitors as code, run a check from your orchestrator the moment a load finishes, and move cases into the tools your team already triages in.

{% hint style="info" %}
These endpoints work with Data Quality V2 monitors only. Classic monitors stay on the [Monitors (classic)](https://docs.decube.io/public-api/overview/index/monitors.md) endpoints. If you're moving an existing integration across, start with [Migrate from Monitors (classic)](https://docs.decube.io/public-api/overview/index/data-quality-v2/migrate-from-monitors-classic.md).
{% endhint %}

## How the objects fit together

A **monitor** holds what you name and tag: its name, description, DQ dimension, custom attributes, and whether it's enabled. What the monitor actually checks — its type, asset, schedule, threshold, and scan method — lives in a **configuration version**. Each execution of that configuration is a **run**. A run that fails raises an **incident**, and Decube groups incidents into a **case** for you to triage.

| Object                | What it represents                                                                                                                                                                           | ID you pass        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| Monitor               | A check on a table, column, or source, and its descriptive properties                                                                                                                        | `monitor_id`       |
| Configuration version | What the monitor checks and when. A [destructive change](https://docs.decube.io/data-quality-v2/monitors/building-blocks.md#destructive-changes-and-monitor-versions) creates a new version. | `configuration_id` |
| Run                   | One execution of a configuration version, either scheduled or triggered on demand                                                                                                            | `run_id`           |
| Incident              | One failed run, with the evidence Decube measured and a debug query                                                                                                                          | `incident_id`      |
| Case                  | The incidents from one configuration version, grouped until you close the case                                                                                                               | `case_id`          |

A few relationships shape how you call the API:

* **One active version per monitor.** Endpoints that accept `configuration_id` return the active version when you leave it out. Pass it to read an earlier version.
* **Runs and cases belong to a version.** When a destructive change creates a new version, run history and cases start fresh on that version. The earlier ones stay reachable through the old `configuration_id`.
* **One open case per version.** A failed run joins the open case for its configuration version. Once you close that case, the next failure opens a new one.

## Conventions

These rules apply to every endpoint in this section:

* **IDs are query parameters**, not path segments. For example, `GET /data_quality/monitors/details?monitor_id=123`.
* **Request bodies are JSON.** Send `Content-Type: application/json` with every `POST`, `PUT`, and `PATCH`.
* **Percentages are decimals.** Send `0.015` for 1.5% and `0.5` for 50%.
* **Decimal values come back as strings.** Thresholds, percentage tolerances, and measured values such as averages return as strings, for example `"0.015"`, so no precision is lost. Requests accept either a number or a string.
* **Timestamps are ISO 8601.** Dates such as `incident_from` use `YYYY-MM-DD`.
* **Errors return HTTP `400`.** Treat any `400` as a failed request and read the response body for details.

### Pagination

List and search endpoints take `page_size` (default `25`, maximum `100`) and `page_number` (default `1`). The response returns `items` along with the `page_number` and `page_size` you requested, without a total count. Keep requesting the next page until a page returns fewer items than `page_size`.

### Full and partial updates

Most update endpoints replace the whole object, so send every field — including the ones you're not changing. The safest pattern is to read the current object, change what you need, and send it back.

[Update a case](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md#update-a-case) is the exception. It accepts a partial body: include a field, wrapped in a `value` object, to change it, and leave it out to keep its current value.

## Quickstart

This example finds the monitors on one table, then fetches the full configuration of one of them.

```bash
export DECUBE_API_KEY="your-api-key"
export DECUBE_BASE="https://connect.<REGION>.decube.io/api/v1/data/data_quality"

# 1. Find every monitor on table 123, including the monitors on its columns
curl -X POST "$DECUBE_BASE/monitors/search" \
  -H "X-Decube-Api-Key: $DECUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filters": { "assets": [{ "type": "dataset", "id": 123 }] } }'

# 2. Fetch one monitor from the results, with its version list
curl "$DECUBE_BASE/monitors/details?monitor_id=456" \
  -H "X-Decube-Api-Key: $DECUBE_API_KEY"
```

## Endpoints

| Task                         | Method   | Path                                   | Page                                                                                                                                      |
| ---------------------------- | -------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Search monitors              | `POST`   | `/data_quality/monitors/search`        | [Monitors](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#find-monitors)                                    |
| Get a monitor                | `GET`    | `/data_quality/monitors/details`       | [Monitors](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#get-a-monitor)                                    |
| Create a monitor             | `POST`   | `/data_quality/monitors`               | [Monitors](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#create-a-monitor)                                 |
| Update monitor properties    | `PUT`    | `/data_quality/monitors/properties`    | [Monitors](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#update-a-monitor)                                 |
| Update monitor configuration | `PUT`    | `/data_quality/monitors/configuration` | [Monitors](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#update-a-monitor)                                 |
| Enable or disable a monitor  | `PATCH`  | `/data_quality/monitors`               | [Monitors](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#enable-or-disable-a-monitor)                      |
| Delete a monitor             | `DELETE` | `/data_quality/monitors`               | [Monitors](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#delete-a-monitor)                                 |
| Trigger a run                | `POST`   | `/data_quality/monitors/trigger`       | [Monitor runs](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitor-runs.md#trigger-a-run)                            |
| Get a run                    | `GET`    | `/data_quality/monitors/runs/details`  | [Monitor runs](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitor-runs.md#check-a-run)                              |
| List runs                    | `GET`    | `/data_quality/monitors/runs`          | [Monitor runs](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitor-runs.md#list-run-history)                         |
| Search cases                 | `POST`   | `/data_quality/cases/search`           | [Cases & incidents](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md#find-cases)                   |
| Get a case                   | `GET`    | `/data_quality/cases/details`          | [Cases & incidents](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md#get-a-case)                   |
| Update a case                | `PATCH`  | `/data_quality/cases`                  | [Cases & incidents](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md#update-a-case)                |
| List a case's incidents      | `GET`    | `/data_quality/cases/incidents`        | [Cases & incidents](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md#list-the-incidents-in-a-case) |
| Get an incident              | `GET`    | `/data_quality/incidents/details`      | [Cases & incidents](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md#get-an-incident)              |

## In this section

{% content-ref url="/pages/tMP9AOPNplJvWQmW2hSe" %}
[Monitors](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md)
{% endcontent-ref %}

{% content-ref url="/pages/UHh0NmL2JguFuluXmRZD" %}
[Monitor runs](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitor-runs.md)
{% endcontent-ref %}

{% content-ref url="/pages/lZEPeESKtRhrZ9VmYBBO" %}
[Cases & incidents](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md)
{% endcontent-ref %}

{% content-ref url="/pages/Fgt5CnJUIBnNsXkopFsh" %}
[Examples](https://docs.decube.io/public-api/overview/index/data-quality-v2/examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/gVcDDsUKDL0SHC5NFUif" %}
[Migrate from Monitors (classic)](https://docs.decube.io/public-api/overview/index/data-quality-v2/migrate-from-monitors-classic.md)
{% endcontent-ref %}
