Create, Manage & Delete

Programmatically manage data quality monitors for your assets so you can monitor various aspects of data quality including freshness, volume, field health and custom rules.

It is highly recommended to review Monitor Validation & Constraints section to understand the required payload structure for creating and updating monitors.

For practical examples, see the Monitor Creation Examples guide.

Deprecation of legacy test types Not Null, Null%, Is Unique, Unique%, Is Email and Is UUID will be done on 30 January 2026. Please use the unified test types Null, Unique, Email and UUID instead. Read more here.

Create Monitor

post

Creates a new monitor with the provided configuration. Returns the created monitor ID.

Body

application/json

assetany ofRequired

or

or

test_typestring · enumRequiredPossible values:

modestring · enumRequiredPossible values:

namestring · max: 100Required

descriptionany ofOptional

string · max: 1000Optional

or

nullOptional

notifybooleanRequired

custom_alertsany ofOptional

or

nullOptional

incident_levelstring · enumRequiredPossible values:

dimensionany ofOptional

string · enumOptionalPossible values:

or

nullOptional

row_creationany ofOptional

or

or

or

nullOptional

frequencyany ofOptional

or

or

or

or

nullOptional

lookback_periodany ofOptional

integer · min: 1Optional

or

nullOptional

custom_sqlany ofOptional

stringOptional

or

nullOptional

total_row_count_queryany ofOptional

stringOptional

or

nullOptional

thresholdany ofOptional

anyOptional

or

or

or

or

or

nullOptional

valueany ofOptional

stringOptional

or

nullOptional

groupingany ofOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/monitors

HTTPcURLJavaScriptPython

POST /api/v1/data/monitors HTTP/1.1
Host: connect.<REGION>.decube.io
Content-Type: application/json
Accept: */*
Content-Length: 546

{
  "asset": {
    "type": "text",
    "id": 1
  },
  "test_type": "volume",
  "mode": "scheduled",
  "name": "text",
  "description": "text",
  "notify": true,
  "custom_alerts": {
    "email": [
      "text"
    ],
    "slack": [
      "text"
    ],
    "teams_webhook": [
      "text"
    ]
  },
  "incident_level": "info",
  "dimension": "accuracy",
  "row_creation": {
    "filter_mode": "text",
    "sql_expression": "text",
    "enable_smart_training": true
  },
  "frequency": {
    "frequency": "1H"
  },
  "lookback_period": 1,
  "custom_sql": "text",
  "total_row_count_query": "text",
  "threshold": {
    "type": "text"
  },
  "value": "text",
  "grouping": {
    "group_by": {
      "type": "text",
      "id": 1
    },
    "groups": [
      "text"
    ]
  }
}

{
  "monitor_id": 1
}

Update Monitor

put

Updates an existing monitor (excluding Schema Drift and Job Failure monitors). Requires full monitor configuration in the request body. Returns the updated monitor ID.

Body

application/json

idintegerRequired

nameany ofOptional

string · max: 100Optional

or

nullOptional

descriptionany ofOptional

string · max: 1000Optional

or

nullOptional

notifybooleanRequired

custom_alertsany ofOptional

or

nullOptional

incident_levelstring · enumRequiredPossible values:

dimensionany ofOptional

string · enumOptionalPossible values:

or

nullOptional

row_creationany ofOptional

or

or

or

nullOptional

frequencyany ofOptional

or

or

or

or

nullOptional

lookback_periodany ofOptional

integer · min: 1Optional

or

nullOptional

custom_sqlany ofOptional

stringOptional

or

nullOptional

total_row_count_queryany ofOptional

stringOptional

or

nullOptional

thresholdany ofOptional

anyOptional

or

or

or

or

or

nullOptional

valueany ofOptional

stringOptional

or

nullOptional

groupsany ofOptional

string[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

put

/monitors

HTTPcURLJavaScriptPython

PUT /api/v1/data/monitors HTTP/1.1
Host: connect.<REGION>.decube.io
Content-Type: application/json
Accept: */*
Content-Length: 435

{
  "id": 1,
  "name": "text",
  "description": "text",
  "notify": true,
  "custom_alerts": {
    "email": [
      "text"
    ],
    "slack": [
      "text"
    ],
    "teams_webhook": [
      "text"
    ]
  },
  "incident_level": "info",
  "dimension": "accuracy",
  "row_creation": {
    "filter_mode": "text",
    "sql_expression": "text",
    "enable_smart_training": true
  },
  "frequency": {
    "frequency": "1H"
  },
  "lookback_period": 1,
  "custom_sql": "text",
  "total_row_count_query": "text",
  "threshold": {
    "type": "text"
  },
  "value": "text",
  "groups": [
    "text"
  ]
}

{
  "monitor_id": 1
}

Delete Monitor

delete

Delete a monitor by ID.

Query parameters

monitor_idinteger · min: 1Required

Unique identifier of the monitor

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

delete

/monitors

HTTPcURLJavaScriptPython

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

No content

Monitor Validation & Constraints

This section documents the request model, validation rules, and conditional requirements for creating and updating monitors. It is important to understand these rules to ensure that the monitors are created and updated correctly.

Monitorable assets

• Allowed asset types for monitors are restricted to: Source, Dataset/Data Asset, Collection, Property/Data Asset Property, Data Job.

• The asset must exist and be active (not deleted) in your organization.

Asset types by test

The following table maps monitor test types to the primary asset types they support. Use this as a quick reference when creating or updating monitors.

Test Type	Primary Asset Type	create_supported
Freshness	dataset	yes
Volume	dataset	yes
Field Health	property	yes
Custom SQL	source	yes
Schema Drift	collection	no
Job Failure	data_job	no

Note: "create_supported" indicates whether the API supports creating a monitor of this test type. "no" means there is no create option via the monitors create endpoint for that test type; these tests are already created upon source connection and only can be updated.

Supported test types by monitor mode

The following table shows which test types are available for each monitor mode:

Test Type	On-Demand Support	Scheduled Support	Notes
Freshness	✅	✅	Dataset-level monitoring
Volume	✅	✅	Dataset-level monitoring
Field Health Tests
Average	✅	✅	Numeric columns only
Min	✅	✅	Numeric columns only
Max	✅	✅	Numeric columns only
Sum	✅	✅	Numeric columns only
Range	✅	✅	Numeric columns only
Not Null	✅	✅	All data types
Null %	✅	✅	All data types
Is Unique	✅	✅	All data types
Unique %	✅	✅	All data types
String Length	✅	✅	String columns only
Is Email	✅	✅	String columns only
Is UUID	✅	✅	String columns only
Value is	✅	✅	String columns only
Value in	✅	✅	String columns only
Regex Match	✅	✅	String columns only
Cardinality	❌	✅	Special restrictions apply
Other Test Types
Custom SQL	✅	✅	Custom query validation required
Schema Drift	❌	✅	Table/Column changes only
Job Failure	❌	✅	Data job monitoring only

Test type capabilities and features

The following table shows which features are supported for each test type across different monitor modes:

Test Type	Grouping Support	Smart Training	Quality Dimensions	Row Creation Required
Dataset-Level Tests
Freshness	✅ (Scheduled only)	✅	❌	✅
Volume	✅ (Scheduled only)	✅	❌	✅
Field Health Tests
Average	✅ (Scheduled only)	✅	❌	✅
Min	✅ (Scheduled only)	✅	❌	✅
Max	✅ (Scheduled only)	✅	❌	✅
Sum	✅ (Scheduled only)	✅	❌	✅
Range	✅ (Scheduled only)	✅	❌	✅
Not Null	✅ (Scheduled only)	❌	✅	✅
Null %	✅ (Scheduled only)	✅	❌	✅
Is Unique	✅ (Scheduled only)	❌	✅	✅
Unique %	✅ (Scheduled only)	✅	❌	✅
String Length	✅ (Scheduled only)	✅	❌	✅
Is Email	✅ (Scheduled only)	❌	✅	✅
Is UUID	✅ (Scheduled only)	❌	✅	✅
Value is	✅ (Scheduled only)	❌	✅	✅
Value in	✅ (Scheduled only)	❌	✅	✅
Regex Match	✅ (Scheduled only)	❌	✅	✅
%Negative	✅ (Scheduled only)	✅	❌	✅
%Zero	✅ (Scheduled only)	✅	❌	✅
Cardinality	❌	❌	❌	✅
Other Test Types
Custom SQL	✅	❌	❌	❌
Schema Drift	❌	❌	❌	❌
Job Failure	❌	❌	❌	❌

Mode and scheduling rules

• mode determines whether a monitor is scheduled or on-demand.

• mode determines whether a monitor is scheduled or on-demand. Use the exact API token values for this field: scheduled or on_demand.

• Scheduled monitors:

  • frequency is required.

• On-demand monitors:

  • frequency must be omitted.

  • Only a subset of test_type values are allowed (see “On-demand compatible tests”).

Frequency shapes and constraints

This controls how often a scheduled monitor runs. The available frequency options depend on the selected row creation mode.

Frequency availability by row creation mode:

Row Creation Mode	Hourly (1H, 3H, 6H, 12H)	Daily	Weekly	Monthly
Timestamp (datetime column)	✅	✅	✅	✅
Timestamp (date column)	❌	✅	✅	✅
SQL Expression	✅	✅	✅	✅
All Records	✅	✅	✅	✅

Frequency object shapes:

Hourly Frequency

{
  "frequency": "1H" | "3H" | "6H" | "12H"
}

• Must NOT include timezone or time-of-day fields

• Not available when using date columns (only datetime)

Daily Frequency

{
  "frequency": "1D",
  "time_of_day": <integer>,
  "timezone": "<string>"
}

• Requires time_of_day (hour of day, 0-23) and timezone

Weekly Frequency

{
  "frequency": "7D",
  "time_of_day": <integer>,
  "day_of_week": <integer>,
  "timezone": "<string>"
}

• Requires time_of_day, day_of_week (0=Sunday, 6=Saturday), and timezone

Monthly Frequency

{
  "frequency": "MS",
  "time_of_day": <integer>,
  "day_of_month": <integer>,
  "timezone": "<string>"
}

• Requires time_of_day, day_of_month, and timezone

• day_of_month: provide integer values 1-28 for monitor to be run on these dates of the month.

  • For monitor to run on every last day of the month, use "day_of_month": 31

Additional validation rules:

• timezone must be a valid IANA time zone (e.g., UTC, America/New_York)

• day_of_week is only valid for weekly frequency; providing it for other frequencies is rejected

• day_of_month is only valid for monthly frequency; providing it for other frequencies is rejected

• time_of_day hour range is validated by the server (0-23)

Row creation modes and constraints

row_creation controls how rows are selected for computing metrics/tests. This setting is required for most test types and has different availability based on the monitor mode and test type.

Row creation mode availability

Test Type	Monitor Mode	Timestamp	SQL Expression	All Records	Notes
Dataset-Level Tests
Freshness	On-demand	✅	✅	❌	Requires time-based filtering
Freshness	Scheduled	✅	✅	✅	All modes supported
Volume	On-demand	✅	✅	✅	All modes supported
Volume	Scheduled	✅	✅	✅	All modes supported
Field Health Tests
All field health	On-demand	✅	✅	✅	All modes supported
All field health	Scheduled	✅	✅	✅	All modes supported
Other Test Types
Custom SQL	On-demand	❌	❌	❌	Row creation not applicable
Custom SQL	Scheduled	❌	❌	❌	Row creation not applicable
Schema Drift	Scheduled	❌	❌	❌	Row creation not applicable
Job Failure	Scheduled	❌	❌	❌	Row creation not applicable

Row creation mode specifications

AllRecordsMode

{
  "filter_mode": "all_records"
}

• Use all rows in the dataset

• No additional fields required

• Smart training is not available for this mode.

TimestampMode

{
  "filter_mode": "timestamp",
  "metric_column_id": <number>,
  "enable_smart_training": <boolean> // optional
}

• Requires metric_column_id referencing a timestamp/datetime column

• Column must exist on the target asset and be timestamp-like data type

• Optionally supports enable_smart_training

SqlExpressionMode

{
  "filter_mode": "sql_expression",
  "sql_expression": "<string>",
  "enable_smart_training": <boolean> // optional
}

• Requires sql_expression (a boolean filter SQL expression)

• Expression is validated for syntax against the underlying source via connector

• Invalid SQL will be rejected with timeout/error if source cannot be reached

• Optionally supports enable_smart_training

Lookback period constraints

Row Creation Mode	Lookback Period Required	Notes
Timestamp	✅	Must be > 0
SQL Expression	✅	Must be > 0
All Records	❌	-

For on-demand monitors, lookback period behavior depends on the row creation mode:

Note: row_creation enum values are case-sensitive; use lowercase values as shown above.

Grouping and group mapping

This allows monitors to be run on specific segments within a table (e.g., by values in a dimension column). See Set Up Grouped-by Monitors for UI setup details.

• is_group_by = true enables grouping; otherwise grouping-related fields are ignored.

• group_by identifies the asset to group by (must be compatible with the target asset and monitor setting).

• groups is an optional allowlist of specific group values to monitor. If provided, it must not exceed the server’s limit (current max is 100 distinct values).

Custom SQL grouping

This allows

• group_mapping is optional and allows mapping the raw grouping values to business labels:

  • Fields: mapping_column_id (column containing raw values), group_by_field_name (target label field name).

• Use the GET /monitors/distinct_groups?column_id=... helper to discover distinct group values for a column.

Alerts and notifications

• notify controls whether alerts are sent. If notify = false, any custom_alerts are ignored.

• custom_alerts supports channels:

  • email: list of addresses

  • slack: list of channel IDs or webhook URLs (org-config dependent)

  • teams_webhook: list of webhook URLs

• If notify = true and custom_alerts is provided, channel values must follow the organization’s connector configuration and be valid.

Thresholds: validation rules and types by test type

Thresholds define the acceptable range or values for a test to pass. The shape and validation rules of the threshold depend on the test_type and mode.

The API now supports multiple threshold types:

• AbsoluteRange: Row count thresholds (e.g., "fail when > 100 rows")

• PercentageRange: Percentage thresholds (e.g., "fail when > 5%")

• AnyRange: Numeric range accepting any integer value

• PositiveRange: Numeric range accepting only non-negative values

• AutoThreshold: Machine learning-based thresholds (scheduled mode only)

Note on Regex Match test: The regex pattern is now specified in the value field of the monitor configuration, not in the threshold. The threshold controls how many non-matching values trigger an incident.

Threshold types and validation rules

Test Type	Monitor Mode	Threshold Type(s)	Validation Rules	Notes
No Threshold Required
Not Null	Both	N/A	No threshold accepted	Automatically fails when null values found
Is Unique	Both	N/A	No threshold accepted	Automatically fails when duplicates found
Is Email	Both	N/A	No threshold accepted	Validates email format
Is UUID	Both	N/A	No threshold accepted	Validates UUID format
Cardinality	Scheduled	N/A	No threshold accepted	Monitors number of distinct values
Freshness	Both	N/A	Auto-learned	Uses historical patterns
Volume	Scheduled	N/A	Auto-learned	Uses historical patterns
Schema Drift	Scheduled	N/A	No threshold accepted	Detects schema changes
Job Failure	Scheduled	N/A	No threshold accepted	Monitors job status
AnyRange Thresholds
Average	Scheduled	AutoThreshold, AnyRange	-∞ ≤ min ≤ max ≤ ∞ max > min At least one bound required	Accepts any numeric value; auto for scheduled
Average	On-demand	AnyRange	-∞ ≤ min ≤ max ≤ ∞ max > min At least one bound required	Accepts any numeric value
Min	Scheduled	AutoThreshold, AnyRange	-∞ ≤ min ≤ max ≤ ∞ max > min At least one bound required	Accepts any numeric value; auto for scheduled
Min	On-demand	AnyRange	-∞ ≤ min ≤ max ≤ ∞ max > min At least one bound required	Accepts any numeric value
Max	Scheduled	AutoThreshold, AnyRange	-∞ ≤ min ≤ max ≤ ∞ max > min At least one bound required	Accepts any numeric value; auto for scheduled
Max	On-demand	AnyRange	-∞ ≤ min ≤ max ≤ ∞ max > min At least one bound required	Accepts any numeric value
PositiveRange Thresholds
String Length	Scheduled	AutoThreshold, PositiveRange	0 ≤ min ≤ max ≤ ∞ max > min At least one bound required	Only non-negative integers; auto for scheduled
String Length	On-demand	PositiveRange	0 ≤ min ≤ max ≤ ∞ max > min At least one bound required	Only non-negative integers
Volume	On-demand	PositiveRange	0 ≤ min ≤ max ≤ ∞ max > min At least one bound required	Only non-negative integers
Percentage & Absolute
Null %	Scheduled	AutoThreshold, PercentageRange	0 ≤ min ≤ max ≤ 100 max > min At least one bound required	Integer values only; auto for scheduled
Null %	On-demand	PercentageRange	0 ≤ min ≤ max ≤ 100 max > min At least one bound required	Integer values only
Unique %	Scheduled	AutoThreshold, PercentageRange	0 ≤ min ≤ max ≤ 100 max > min At least one bound required	Integer values only; auto for scheduled
Unique %	On-demand	PercentageRange	0 ≤ min ≤ max ≤ 100 max > min At least one bound required	Integer values only
Null	Scheduled	AutoThreshold, AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
Null	On-demand	AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
Unique	Scheduled	AutoThreshold, AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
Unique	On-demand	AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
Email	Scheduled	AutoThreshold, AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
Email	On-demand	AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
UUID	Scheduled	AutoThreshold, AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
UUID	On-demand	AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
Regex Match	Scheduled	AutoThreshold, AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
Regex Match	On-demand	AbsoluteRange, PercentageRange	0 ≤ min ≤ max max > min At least one bound required	Supports both absolute and percentage
Custom SQL
Custom SQL	Scheduled	AbsoluteRange, PercentageRange*	0 ≤ min ≤ max max > min At least one bound required	*Percentage requires DQ Scorecard toggle enabled
Custom SQL	On-demand	AbsoluteRange, PercentageRange*	0 ≤ min ≤ max max > min At least one bound required	*Percentage requires DQ Scorecard toggle enabled

• Note for CustomSQL monitor: PercentageRange thresholds can only be set when total_row_count_query is provided in the payload. This is to allow calculation of percentage-based metrics by defining the total row count for the CustomSQL monitor.

Threshold object shapes

The API accepts discriminated threshold object shapes. Each shape includes a required type field whose value is a literal constant that determines which threshold type is being used:

AbsoluteRange

{
  "type": "absolute",
  "min": <integer|null>,
  "max": <integer|null>
}

• Used for absolute row count thresholds

• min and max may be null to indicate an open bound

• At least one bound (min or max) must be non-null

• Both values must be non-negative integers (≥ 0)

• If both are provided: max > min

• Example: {"type": "absolute", "min": null, "max": 100} - fails when > 100 rows

PercentageRange

{
  "type": "percentage",
  "min": <integer|null>,
  "max": <integer|null>
}

• Used for percentage-based thresholds

• min and max may be null to indicate an open bound

• At least one bound (min or max) must be non-null

• Values must be integers between 0 and 100 (inclusive)

• If both are provided: max > min

• Example: {"type": "percentage", "min": null, "max": 5} - fails when > 5%

AnyRange

{
  "type": "any_range",
  "min": <integer|null>,
  "max": <integer|null>
}

• Used for numeric field tests that accept any integer value (positive or negative)

• min and max may be null to indicate an open bound

• At least one bound (min or max) must be non-null

• Accepts any integer value from -∞ to +∞

• If both are provided: max > min

• Commonly used for: Average, Min, Max tests

• Example: {"type": "any_range", "min": -100, "max": 100}

PositiveRange

{
  "type": "positive_range",
  "min": <integer|null>,
  "max": <integer|null>
}

• Used for tests that only accept non-negative integer values

• min and max may be null to indicate an open bound

• At least one bound (min or max) must be non-null

• Both values must be non-negative integers (≥ 0)

• If both are provided: max > min

• Commonly used for: String Length, Volume (on-demand)

• Example: {"type": "positive_range", "min": 0, "max": 255}

AutoThreshold

{
  "type": "auto"
}

• Available for scheduled monitors that support machine learning

• Server auto-learns thresholds from historical data

• No additional fields required

• Only available for scheduled mode monitors

Test-type specific notes

• Schema Drift tests (table_addition, table_deletion, column_addition, column_deletion, column_type_change) and Job Failure tests have their own specialized behavior and do not use thresholds, grouping, or row creation like field-health tests

• Freshness and Volume monitors (dataset-level) use auto-learned thresholds in scheduled mode and do not accept manual thresholds

• Custom SQL monitors:

  • Require query validation before submission

  • Support both AbsoluteRange and PercentageRange thresholds

  • PercentageRange requires "Include this monitor into Data Quality Scorecard" toggle to be enabled

  • When DQ Scorecard toggle is disabled, only AbsoluteRange is available

• New threshold-based tests (Null, Unique, Email, UUID, Regex Match):

  • Support both AbsoluteRange (row count) and PercentageRange (percentage) modes

  • Support AutoThreshold in scheduled mode

  • For Regex Match: the regex pattern is specified in the monitor's value field, not in the threshold

Names and descriptions

• name: required, max 100 characters.

• description: optional, max 1000 characters.

• Name uniqueness is enforced within an asset/test-type/mode combination; if violated, requests will be rejected.

Time zones

• timezone must be a valid IANA time zone. Invalid zones are rejected.

Appendix: Quick Field reference

• Frequency unions:

  • Hourly: {"frequency": "1H|3H|6H|12H"}

  • Daily: {"frequency": "1D", "time_of_day": int, "timezone": string}

  • Weekly: {"frequency": "7D", "time_of_day": int, "day_of_week": int, "timezone": string}

  • Monthly: {"frequency": "MS", "time_of_day": int, "day_of_month": int, "timezone": string}

    • acceptable values for day_of_month: 1-28, 31

• Row creation unions (literal filter_mode values):

  • All: { "filter_mode": "all_records" }

  • Timestamp: { "filter_mode": "timestamp", "metric_column_id": number, "enable_smart_training"?: boolean }

  • SQL expression: { "filter_mode": "sql_expression", "sql_expression": string, "enable_smart_training"?: boolean }

• Thresholds:

  • AbsoluteRange: { "type": "absolute", "min": <integer|null>, "max": <integer|null> } (non-negative values)

  • PercentageRange: { "type": "percentage", "min": <integer|null>, "max": <integer|null> } (0-100)

  • AnyRange: { "type": "any_range", "min": <integer|null>, "max": <integer|null> } (any integer)

  • PositiveRange: { "type": "positive_range", "min": <integer|null>, "max": <integer|null> } (non-negative values)

  • AutoThreshold: { "type": "auto" }