Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Monitors

Search, create, update, enable, disable, and delete Data Quality V2 monitors through the Public API

The Monitors endpoints let you manage Data Quality V2 monitors as code. You can keep monitor definitions in version control, roll out the same checks across many tables, and audit your monitor inventory from outside Decube. Each endpoint mirrors an action in the Monitors tab, so a monitor you create through the API looks and behaves exactly like one created in the UI.

New to the monitor settings? Building Blocks explains schedules, detection and scan methods, thresholds, and tolerances. This page covers how to express them in a request.

Search monitors

Search returns monitors that match a name query and any combination of filters. Every field in the body is optional — an empty body {} returns all the monitors you can view.

Search Monitors

post

Search monitors by name and filters.

Body
querystring · nullableOptional

Search term to match against the monitor name (substring match, case insensitive)

page_sizeinteger · min: 1 · max: 100Optional

Number of results per page

Default: 25
page_numberinteger · min: 1 · max: 100000Optional

Page number of the results

Default: 1
Responses
200

Successful Response

application/json
page_numberintegerRequired
page_sizeintegerRequired
post/data_quality/monitors/search
POST /api/v1/data/data_quality/monitors/search HTTP/1.1
Host: connect.<REGION>.decube.io
Content-Type: application/json
Accept: */*
Content-Length: 309

{
  "query": "text",
  "filters": {
    "assets": [
      {
        "type": "text",
        "id": 1
      }
    ],
    "monitor_types": [
      "freshness_sla"
    ],
    "schedules": [
      "manual"
    ],
    "statuses": [
      "active"
    ],
    "last_run_states": [
      "not_evaluated"
    ],
    "custom_attributes": [
      {
        "config_id": 1,
        "operator": "AND",
        "type": "text",
        "condition": "text",
        "value": true
      }
    ]
  },
  "page_size": 25,
  "page_number": 1
}
{
  "items": [
    {
      "id": 1,
      "name": "text",
      "description": "text",
      "dq_dimension": "accuracy",
      "source_id": 1,
      "enabled": true,
      "invalid_reason": "primary_asset_incompatible_type",
      "configuration": {
        "id": 1,
        "version_number": 1,
        "next_scheduled_at": "2026-01-01T00:00:00.000Z",
        "last_run_state": "queued",
        "last_run_state_updated_at": "2026-01-01T00:00:00.000Z",
        "type": "text",
        "schedule": {
          "frequency": "every_30_minutes"
        },
        "threshold": {
          "type": "text",
          "value": 1,
          "unit": "minutes"
        },
        "detection_method": {
          "type": "text"
        },
        "primary_asset": {
          "asset": {
            "type": "text",
            "name": "text",
            "id": 1,
            "subtype": "bigquery",
            "qual_id": "text",
            "icon": {
              "type": "text",
              "icon": "airbyte"
            }
          },
          "parents": [
            {
              "type": "text",
              "name": "text",
              "id": 1,
              "subtype": "bigquery",
              "qual_id": "text",
              "icon": {
                "type": "text",
                "icon": "airbyte"
              }
            }
          ],
          "assets": [
            {
              "type": "text",
              "name": "text",
              "id": 1,
              "subtype": "bigquery",
              "qual_id": "text",
              "icon": {
                "type": "text",
                "icon": "airbyte"
              }
            }
          ],
          "attrs": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      },
      "custom_attributes": [
        {
          "id": 1,
          "type": "text",
          "label": "text",
          "description": "text",
          "management_type": "user",
          "system_identifier": "constraints",
          "value": "text"
        }
      ],
      "has_edit_permission": true
    }
  ],
  "page_number": 1,
  "page_size": 1
}

Filtering by asset

Each entry in filters.assets is an asset type and id, where type is source, collection, dataset, or property. Two rules apply:

  • One asset type per request. You can list several tables, or several schemas, but not a mix of both.

  • An asset selects what's under it. A table selects the monitors on that table and on its columns. A schema or table also selects the Custom SQL monitors linked to it or to an asset under it.

Get a monitor

Returns one monitor with its active configuration, plus a list of every version of that monitor, newest first.

Get Monitor Details

get

Get monitor details. Exclude configuration_id to get the monitor active version.

Query parameters
monitor_idintegerRequired
configuration_idinteger · nullableOptional
Responses
200

Successful Response

application/json
get/data_quality/monitors/details
GET /api/v1/data/data_quality/monitors/details?monitor_id=1 HTTP/1.1
Host: connect.<REGION>.decube.io
Accept: */*
{
  "monitor": {
    "id": 1,
    "name": "text",
    "description": "text",
    "dq_dimension": "accuracy",
    "source_id": 1,
    "enabled": true,
    "invalid_reason": "primary_asset_incompatible_type",
    "configuration": {
      "id": 1,
      "version_number": 1,
      "next_scheduled_at": "2026-01-01T00:00:00.000Z",
      "last_run_state": "queued",
      "last_run_state_updated_at": "2026-01-01T00:00:00.000Z",
      "type": "text",
      "schedule": {
        "frequency": "every_30_minutes"
      },
      "threshold": {
        "type": "text",
        "value": 1,
        "unit": "minutes"
      },
      "detection_method": {
        "type": "text"
      },
      "primary_asset": {
        "asset": {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        },
        "parents": [
          {
            "type": "text",
            "name": "text",
            "id": 1,
            "subtype": "bigquery",
            "qual_id": "text",
            "icon": {
              "type": "text",
              "icon": "airbyte"
            }
          }
        ],
        "assets": [
          {
            "type": "text",
            "name": "text",
            "id": 1,
            "subtype": "bigquery",
            "qual_id": "text",
            "icon": {
              "type": "text",
              "icon": "airbyte"
            }
          }
        ],
        "attrs": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    },
    "custom_attributes": [
      {
        "id": 1,
        "type": "text",
        "label": "text",
        "description": "text",
        "management_type": "user",
        "system_identifier": "constraints",
        "value": "text"
      }
    ],
    "has_edit_permission": true
  },
  "versions": [
    {
      "id": 1,
      "version_number": 1,
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Each entry in versions carries the version's id — this is the configuration_id you pass to read that version, its runs, or its cases.

Parameter
Notes

configuration_id

Returns this version instead of the active one

A few fields in the response help you decide what to do next:

  • enabled — whether the monitor is scheduled to run.

  • invalid_reason — why a monitor has the invalid status. An invalid monitor doesn't run and can't be triggered. See Invalid reasons.

  • configuration.last_run_state and configuration.next_scheduled_at — the latest outcome and the next scheduled run for this version.

  • has_edit_permission — whether your API key can change this monitor.

Invalid reasons

invalid_reason

What changed

primary_asset_not_found

The table, column, or source the monitor checks no longer exists

primary_asset_incompatible_type

The monitored column's data type no longer suits the monitor type

timestamp_column_not_found

The timestamp column used for detection or scanning no longer exists

timestamp_incompatible_type

The timestamp column's data type is no longer a date or timestamp

source_incompatible_with_detection_method

The source doesn't support the monitor's detection method

To fix an invalid monitor, update its configuration to point at a valid column, or create a new monitor if the asset itself is gone.

Create a monitor

A create request has two parts: the monitor's properties at the top level, and its configuration. The configuration.type sets the monitor type and decides which fields the rest of the configuration needs.

Create Monitor

post

Create a monitor.

Body
namestring · max: 500Required

Name of the monitor

descriptionstring · max: 8000 · nullableOptional

Description of the monitor

dq_dimensionstring · enumRequired

Data quality dimension the monitor measures

Possible values:
configurationone ofRequired

Configuration of the monitor. The type field selects the monitor type and the fields it requires.

or
or
or
or
or
or
or
or
or
or
Responses
200

Successful Response

application/json
idintegerRequired
namestringRequired
descriptionstring · nullableRequired
dq_dimensionstring · enumRequiredPossible values:
source_idintegerRequired
enabledbooleanRequired
invalid_reasonstring · enum · nullableRequiredPossible values:
configurationone ofRequired
or
or
or
or
or
or
or
or
or
or
has_edit_permissionbooleanRequired
post/data_quality/monitors
POST /api/v1/data/data_quality/monitors HTTP/1.1
Host: connect.<REGION>.decube.io
Content-Type: application/json
Accept: */*
Content-Length: 327

{
  "name": "text",
  "description": "text",
  "dq_dimension": "accuracy",
  "configuration": {
    "type": "text",
    "schedule": {
      "frequency": "every_30_minutes"
    },
    "threshold": {
      "type": "text",
      "value": 1,
      "unit": "minutes"
    },
    "detection_method": {
      "type": "text"
    },
    "primary_asset": {
      "type": "text",
      "id": 1
    }
  },
  "custom_attributes": [
    {
      "type": "text",
      "id": 1,
      "value": "text"
    }
  ]
}
{
  "id": 1,
  "name": "text",
  "description": "text",
  "dq_dimension": "accuracy",
  "source_id": 1,
  "enabled": true,
  "invalid_reason": "primary_asset_incompatible_type",
  "configuration": {
    "id": 1,
    "version_number": 1,
    "next_scheduled_at": "2026-01-01T00:00:00.000Z",
    "last_run_state": "queued",
    "last_run_state_updated_at": "2026-01-01T00:00:00.000Z",
    "type": "text",
    "schedule": {
      "frequency": "every_30_minutes"
    },
    "threshold": {
      "type": "text",
      "value": 1,
      "unit": "minutes"
    },
    "detection_method": {
      "type": "text"
    },
    "primary_asset": {
      "asset": {
        "type": "text",
        "name": "text",
        "id": 1,
        "subtype": "bigquery",
        "qual_id": "text",
        "icon": {
          "type": "text",
          "icon": "airbyte"
        }
      },
      "parents": [
        {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        }
      ],
      "assets": [
        {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        }
      ],
      "attrs": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  },
  "custom_attributes": [
    {
      "id": 1,
      "type": "text",
      "label": "text",
      "description": "text",
      "management_type": "user",
      "system_identifier": "constraints",
      "value": "text"
    }
  ],
  "has_edit_permission": true
}

Choose a monitor type and asset

Each monitor type runs on one kind of asset, set in configuration.primary_asset. Follow the link for each type to see what it checks and how its settings behave.

configuration.type
primary_asset.type
Manual schedule availability
Guide

freshness_sla

dataset

No

freshness_staleness

dataset

Yes

volume

dataset

No

average, minimum, maximum, sum

property

Yes, with full table scan

range

property

Yes, with full table scan

string_length, regex_match, regex_not_match

property

Yes, with full table scan

value_in, value_not_in

property

Yes, with full table scan

null, unique, zero

property

Yes, with full table scan

is_before, is_after

property

Yes, with full table scan

custom_sql

source

Yes

A Custom SQL monitor runs against a source. To tie its results to specific tables or columns, add up to 10 attribution_assets (dataset or property) from that same source. Send null or an empty list to attribute the monitor to the source.

Configuration settings

Each type uses a subset of these settings. The API reference below lists the exact fields per type.

schedule — how often the monitor runs. Frequencies that run at a set time also need start_time and timezone.

frequency
Also requires

manual

Nothing. The monitor runs only when you trigger it.

every_30_minutes, every_hour

Nothing

every_3_hours, every_6_hours, every_12_hours, daily

start_time, timezone

weekly

day_of_week (0 is Monday), start_time, timezone

first_day_of_month, last_day_of_month

start_time, timezone

monthly

day_of_month (1–28), start_time, timezone

  • Set timezone as a named zone, { "type": "zone", "name": "Asia/Singapore" }, to follow local time through daylight saving changes.

  • Set it as a fixed offset, { "type": "offset", "offset": "+08:00" }, to stay on the same UTC time all year. Decube schedules runs on 30-minute boundaries, so offsets and zones must fall on the hour or half hour. Schedule covers the difference in more detail.

threshold — the bounds a measured value must stay within. Set at least one of min or max. Both bounds are inclusive: a value fails when it falls below min or above max.

Monitor types
Threshold type

freshness_sla, freshness_staleness

duration, with value and a unit of minutes, hours, or days

volume

count_delta or percentage_delta, set inside detection_method.threshold. Column detection accepts count_delta only.

average, minimum, maximum, sum, range

numeric_range

string_length

integer_range

tolerance — how many failing rows a row-level check accepts before it fails.

  • Use { "type": "absolute", "value": 10 } for a row count,

  • or { "type": "percentage", "value": 0.01 } for a share of rows.

The check fails when the failing rows exceed the tolerance. Send null for a tolerance of zero. A Custom SQL monitor needs a search_space_query to use a percentage tolerance.

scan_method — which rows a Field Health monitor checks.

  • Use { "type": "full_table_scan" } to check every row,

  • or incremental_scan with either a timestamp column or a SQL expression to check only new rows.

See Scan method.

detection_method — how a Freshness or Volume monitor measures the table: from table metadata, from a timestamp column, or, for Volume, a full_table_count. See Detection Method.

Example: create a Null check

This request creates a Null check on column 4521 that runs daily at 06:00 Singapore time and fails when any row is null.

The response is the new monitor, including its id and the configuration.id of its first version. Examples has more complete requests, including Freshness, Volume, and Custom SQL.

Update a monitor

A monitor has two update endpoints, one for its properties and one for its configuration. Pick the endpoint by what you're changing:

You're changing
Endpoint
Creates a new version?

Name, description, DQ dimension, custom attributes

PUT /data_quality/monitors/properties

Never

Schedule, threshold, tolerance, scan or detection method, SQL, values, pattern

PUT /data_quality/monitors/configuration

Yes, unless you change only the threshold or tolerance

Update Monitor Properties

put

Update the name, description, DQ dimension, and custom attributes of a monitor.

Body
monitor_idintegerRequired
namestring · max: 500Required
descriptionstring · max: 8000 · nullableRequired
dq_dimensionstring · enumRequiredPossible values:
Responses
200

Successful Response

application/json
idintegerRequired
namestringRequired
descriptionstring · nullableRequired
dq_dimensionstring · enumRequiredPossible values:
source_idintegerRequired
enabledbooleanRequired
invalid_reasonstring · enum · nullableRequiredPossible values:
configurationone ofRequired
or
or
or
or
or
or
or
or
or
or
has_edit_permissionbooleanRequired
put/data_quality/monitors/properties
PUT /api/v1/data/data_quality/monitors/properties HTTP/1.1
Host: connect.<REGION>.decube.io
Content-Type: application/json
Accept: */*
Content-Length: 137

{
  "monitor_id": 1,
  "name": "text",
  "description": "text",
  "dq_dimension": "accuracy",
  "custom_attributes": [
    {
      "type": "text",
      "id": 1,
      "value": "text"
    }
  ]
}
{
  "id": 1,
  "name": "text",
  "description": "text",
  "dq_dimension": "accuracy",
  "source_id": 1,
  "enabled": true,
  "invalid_reason": "primary_asset_incompatible_type",
  "configuration": {
    "id": 1,
    "version_number": 1,
    "next_scheduled_at": "2026-01-01T00:00:00.000Z",
    "last_run_state": "queued",
    "last_run_state_updated_at": "2026-01-01T00:00:00.000Z",
    "type": "text",
    "schedule": {
      "frequency": "every_30_minutes"
    },
    "threshold": {
      "type": "text",
      "value": 1,
      "unit": "minutes"
    },
    "detection_method": {
      "type": "text"
    },
    "primary_asset": {
      "asset": {
        "type": "text",
        "name": "text",
        "id": 1,
        "subtype": "bigquery",
        "qual_id": "text",
        "icon": {
          "type": "text",
          "icon": "airbyte"
        }
      },
      "parents": [
        {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        }
      ],
      "assets": [
        {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        }
      ],
      "attrs": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  },
  "custom_attributes": [
    {
      "id": 1,
      "type": "text",
      "label": "text",
      "description": "text",
      "management_type": "user",
      "system_identifier": "constraints",
      "value": "text"
    }
  ],
  "has_edit_permission": true
}

Update Monitor Configuration

put

Update the configuration of a monitor.

Body
monitor_idintegerRequired
configurationone ofRequired
or
or
or
or
or
or
or
or
or
or
Responses
200

Successful Response

application/json
idintegerRequired
namestringRequired
descriptionstring · nullableRequired
dq_dimensionstring · enumRequiredPossible values:
source_idintegerRequired
enabledbooleanRequired
invalid_reasonstring · enum · nullableRequiredPossible values:
configurationone ofRequired
or
or
or
or
or
or
or
or
or
or
has_edit_permissionbooleanRequired
put/data_quality/monitors/configuration
PUT /api/v1/data/data_quality/monitors/configuration HTTP/1.1
Host: connect.<REGION>.decube.io
Content-Type: application/json
Accept: */*
Content-Length: 182

{
  "monitor_id": 1,
  "configuration": {
    "type": "text",
    "schedule": {
      "frequency": "every_30_minutes"
    },
    "threshold": {
      "type": "text",
      "value": 1,
      "unit": "minutes"
    },
    "detection_method": {
      "type": "text"
    }
  }
}
{
  "id": 1,
  "name": "text",
  "description": "text",
  "dq_dimension": "accuracy",
  "source_id": 1,
  "enabled": true,
  "invalid_reason": "primary_asset_incompatible_type",
  "configuration": {
    "id": 1,
    "version_number": 1,
    "next_scheduled_at": "2026-01-01T00:00:00.000Z",
    "last_run_state": "queued",
    "last_run_state_updated_at": "2026-01-01T00:00:00.000Z",
    "type": "text",
    "schedule": {
      "frequency": "every_30_minutes"
    },
    "threshold": {
      "type": "text",
      "value": 1,
      "unit": "minutes"
    },
    "detection_method": {
      "type": "text"
    },
    "primary_asset": {
      "asset": {
        "type": "text",
        "name": "text",
        "id": 1,
        "subtype": "bigquery",
        "qual_id": "text",
        "icon": {
          "type": "text",
          "icon": "airbyte"
        }
      },
      "parents": [
        {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        }
      ],
      "assets": [
        {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        }
      ],
      "attrs": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  },
  "custom_attributes": [
    {
      "id": 1,
      "type": "text",
      "label": "text",
      "description": "text",
      "management_type": "user",
      "system_identifier": "constraints",
      "value": "text"
    }
  ],
  "has_edit_permission": true
}

Both endpoints replace what they update, so send the complete object each time:

  • Properties — send name, description, dq_dimension, and custom_attributes. Send "description": null to clear the description and "custom_attributes": [] to remove all attributes.

  • Configuration — send the full configuration for the monitor's type. configuration.type must match the monitor's current type. The primary asset isn't part of the update. For Custom SQL monitors, attribution_assets is required — send [] to attribute the monitor to its source.

Most configuration changes are destructive: Decube archives the current version and makes the new one active. Changing only threshold, tolerance, or a Volume monitor's detection_method.threshold updates the current version in place. Changing the pattern of a Regex monitor or the values of a Value Set monitor is destructive.

Enable or disable a monitor

Disabling a monitor stops its scheduled runs without changing its configuration, so you can resume it later exactly as it was. Enabling it again recalculates its next scheduled run.

Update Monitor

patch

Enable or disable a monitor.

Body
monitor_idintegerRequired

Unique identifier of the monitor

actionone ofRequired

Action to apply, enable or disable a monitor

or
Responses
200

Successful Response

application/json
idintegerRequired
namestringRequired
descriptionstring · nullableRequired
dq_dimensionstring · enumRequiredPossible values:
source_idintegerRequired
enabledbooleanRequired
invalid_reasonstring · enum · nullableRequiredPossible values:
configurationone ofRequired
or
or
or
or
or
or
or
or
or
or
has_edit_permissionbooleanRequired
patch/data_quality/monitors
PATCH /api/v1/data/data_quality/monitors HTTP/1.1
Host: connect.<REGION>.decube.io
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "monitor_id": 1,
  "action": {
    "type": "text"
  }
}
{
  "id": 1,
  "name": "text",
  "description": "text",
  "dq_dimension": "accuracy",
  "source_id": 1,
  "enabled": true,
  "invalid_reason": "primary_asset_incompatible_type",
  "configuration": {
    "id": 1,
    "version_number": 1,
    "next_scheduled_at": "2026-01-01T00:00:00.000Z",
    "last_run_state": "queued",
    "last_run_state_updated_at": "2026-01-01T00:00:00.000Z",
    "type": "text",
    "schedule": {
      "frequency": "every_30_minutes"
    },
    "threshold": {
      "type": "text",
      "value": 1,
      "unit": "minutes"
    },
    "detection_method": {
      "type": "text"
    },
    "primary_asset": {
      "asset": {
        "type": "text",
        "name": "text",
        "id": 1,
        "subtype": "bigquery",
        "qual_id": "text",
        "icon": {
          "type": "text",
          "icon": "airbyte"
        }
      },
      "parents": [
        {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        }
      ],
      "assets": [
        {
          "type": "text",
          "name": "text",
          "id": 1,
          "subtype": "bigquery",
          "qual_id": "text",
          "icon": {
            "type": "text",
            "icon": "airbyte"
          }
        }
      ],
      "attrs": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  },
  "custom_attributes": [
    {
      "id": 1,
      "type": "text",
      "label": "text",
      "description": "text",
      "management_type": "user",
      "system_identifier": "constraints",
      "value": "text"
    }
  ],
  "has_edit_permission": true
}

Delete a monitor

Delete Monitor

delete

Delete a monitor.

Query parameters
monitor_idintegerRequired
Responses
200

Successful Response

application/json
anyOptional
delete/data_quality/monitors
DELETE /api/v1/data/data_quality/monitors?monitor_id=1 HTTP/1.1
Host: connect.<REGION>.decube.io
Accept: */*

No content

Frequently Asked Questions

Can I change a monitor's type or asset?

No. The monitor type and primary asset are fixed when you create the monitor. To check a different asset or use a different type, create a new monitor and delete or disable the old one.

Why did my update create a new version?

The change was destructive — it changed what the monitor checks, so Decube keeps the old results separate. Only threshold, tolerance, and a Volume monitor's detection_method.threshold update the current version in place.

To see every version, call Get a monitor and read versions.

Why does search return monitors in a different order than the Monitors tab?

The API sorts by monitor id so that pagination stays stable. The Monitors tab sorts by the time of the latest run.

Which monitor types can I create through the API?

Every type in Choose a monitor type and asset. These are the same types you can create in the Data Quality V2 module.

Last updated