> 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/migrate-from-monitors-classic.md).

# Migrate from Monitors (classic)

Move an integration from the Monitors (classic) endpoints to the Data Quality V2 endpoints

Data Quality V2 monitors have their own endpoints under `/data_quality`. The [Monitors (classic)](https://docs.decube.io/public-api/overview/index/monitors.md) endpoints keep working for classic monitors while both modules run side by side, but they don't return or accept V2 monitors. When your monitors move to V2, point your integration at the endpoints on this page.

The host, API key, and `X-Decube-Api-Key` header stay the same. Only the paths and payloads change:

```
Classic:  https://connect.<REGION>.decube.io/api/v1/data/monitors/search
V2:       https://connect.<REGION>.decube.io/api/v1/data/data_quality/monitors/search
```

{% hint style="warning" %}
A monitor migrated to Data Quality V2 has a new ID. Update any monitor IDs your integration stores, such as the IDs a pipeline uses to trigger checks.
{% endhint %}

## Endpoint mapping

| Task                | Classic                         | Data Quality V2                                                                                                        |
| ------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Search monitors     | `POST /monitors/search`         | `POST /data_quality/monitors/search`                                                                                   |
| Get a monitor       | `GET /monitors`                 | `GET /data_quality/monitors/details`                                                                                   |
| Create a monitor    | `POST /monitors`                | `POST /data_quality/monitors`                                                                                          |
| Update a monitor    | `PUT /monitors`                 | `PUT /data_quality/monitors/properties` and `PUT /data_quality/monitors/configuration`                                 |
| Enable or disable   | `POST /monitors/enable-disable` | `PATCH /data_quality/monitors`                                                                                         |
| Delete a monitor    | `DELETE /monitors`              | `DELETE /data_quality/monitors`                                                                                        |
| Trigger a run       | `POST /monitors/trigger`        | `POST /data_quality/monitors/trigger`                                                                                  |
| Check a run         | `GET /monitors/status`          | `GET /data_quality/monitors/runs/details`                                                                              |
| Run history         | `GET /monitors/history`         | `GET /data_quality/monitors/runs`                                                                                      |
| Cases and incidents | —                               | [Cases & incidents](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md) endpoints |

## What changes in the payloads

### Monitor definition

A classic monitor is defined by `asset`, `test_type`, `mode`, and `frequency` at the top level. A V2 monitor keeps its properties at the top level and moves everything it checks into `configuration`:

* **`test_type` → `configuration.type`.** V2 splits some classic types into more specific ones. See [Monitor type mapping](#monitor-type-mapping).
* **`asset` → `configuration.primary_asset`.** The asset type must match the monitor type.
* **`mode` and `frequency` → `configuration.schedule`.** On-demand monitors become monitors with `"frequency": "manual"`. Scheduled monitors use the V2 [schedule shapes](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#configuration-settings), which add named timezones and more monthly options.
* **`row_creation` → `configuration.scan_method`** for Field Health monitors, and **`configuration.detection_method`** for Freshness and Volume.
* **`notify` and `incident_level` → alert rules.** V2 routes incidents through [alert rules](https://docs.decube.io/data-quality-v2/alerts/how-alert-rules-work.md) instead of per-monitor flags.
* **New: `dq_dimension`** is required on every V2 monitor.

### Updates

Classic uses a single update endpoint. V2 splits it in two: one for the properties you name and tag, and one for the configuration that defines the check. Configuration changes can create a new monitor version. See [Update a monitor](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitors.md#update-a-monitor).

### Enable, disable, and delete

Enabling and disabling use `PATCH /data_quality/monitors` with an `action` of `enable` or `disable`, in place of an `enabled` flag. Deleting is a separate `DELETE` request with `monitor_id` as a query parameter.

### Runs and results

A V2 trigger returns a `run_id`. Check that run directly with [Check a run](https://docs.decube.io/public-api/overview/index/data-quality-v2/monitor-runs.md#check-a-run) instead of polling the monitor's status. Failed runs raise incidents grouped into cases, which you read and update through the [Cases & incidents](https://docs.decube.io/public-api/overview/index/data-quality-v2/cases-and-incidents.md) endpoints.

## Monitor type mapping

| Classic test type         | V2 `configuration.type`                  | Notes                                                                                                          |
| ------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Freshness                 | `freshness_sla` or `freshness_staleness` | See [Freshness](https://docs.decube.io/data-quality-v2/monitor-types/freshness-sla-and-staleness.md) to choose |
| Volume                    | `volume`                                 |                                                                                                                |
| Average, Min, Max, Sum    | `average`, `minimum`, `maximum`, `sum`   |                                                                                                                |
| Range                     | `range`                                  |                                                                                                                |
| Not Null, Null %          | `null`                                   | Use an absolute tolerance of `0` for Not Null, or a percentage tolerance for Null %                            |
| Is Unique, Unique %       | `unique`                                 | Same tolerance approach as Null                                                                                |
| %Zero                     | `zero`                                   | Use a percentage tolerance                                                                                     |
| String Length             | `string_length`                          |                                                                                                                |
| Is Email, Is UUID         | `regex_match`                            | Use the `email` or `uuid` pattern preset                                                                       |
| Regex Match               | `regex_match`                            | V2 also adds `regex_not_match`                                                                                 |
| Value is, Value in        | `value_in`                               | V2 also adds `value_not_in`                                                                                    |
| Custom SQL                | `custom_sql`                             | Links to tables through `attribution_assets`                                                                   |
| Schema Drift, Job Failure | Not yet available in V2                  |                                                                                                                |

## Migration checklist

1. List the classic endpoints your integration calls and find each one in the [endpoint mapping](#endpoint-mapping).
2. Rewrite monitor definitions into the V2 shape, including a `dq_dimension` for each.
3. Replace stored classic monitor IDs with the new V2 IDs.
4. Switch on-demand monitors that your pipelines trigger to a `manual` schedule, and update the polling code to read the run by `run_id`.
5. Recreate any notification behaviour as [alert rules](https://docs.decube.io/data-quality-v2/alerts.md).
6. Test against a few monitors before switching your whole integration.
