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.
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 by name and filters.
Search term to match against the monitor name (substring match, case insensitive)
Number of results per page
25Page number of the results
1Successful Response
Validation Error
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. Exclude configuration_id to get the monitor active version.
Successful Response
Validation Error
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.
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 theinvalidstatus. An invalid monitor doesn't run and can't be triggered. See Invalid reasons.configuration.last_run_stateandconfiguration.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 a monitor.
Name of the monitor
Description of the monitor
Data quality dimension the monitor measures
Configuration of the monitor. The type field selects the monitor type and the fields it requires.
Successful Response
Validation Error
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.
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.
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
timezoneas 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.
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_scanwith 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:
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 the name, description, DQ dimension, and custom attributes of a monitor.
Successful Response
Validation Error
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 the configuration of a monitor.
Successful Response
Validation Error
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, andcustom_attributes. Send"description": nullto clear the description and"custom_attributes": []to remove all attributes.Configuration — send the full
configurationfor the monitor's type.configuration.typemust match the monitor's current type. The primary asset isn't part of the update. For Custom SQL monitors,attribution_assetsis 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.
Enable or disable a monitor.
Unique identifier of the monitor
Action to apply, enable or disable a monitor
Successful Response
Validation Error
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 a monitor.
Successful Response
Validation Error
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