Try for free

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.

Create Monitor

post

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

Body
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
thresholdany ofOptional
or
or
or
or
nullOptional
groupingany ofOptional
or
nullOptional
Responses
200

Successful Response

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

{
  "asset": {
    "type": "text",
    "id": 1
  },
  "test_type": "volume",
  "mode": "scheduled",
  "name": "text",
  "description": "text",
  "notify": true,
  "custom_alerts": {
    "email": [],
    "slack": [
      "text"
    ],
    "teams_webhook": []
  },
  "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",
  "threshold": {
    "type": "text",
    "min": 1,
    "max": 1
  },
  "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
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
thresholdany ofOptional
or
or
or
or
nullOptional
groupsany ofOptional
string[]Optional
or
nullOptional
Responses
200

Successful Response

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

{
  "id": 1,
  "name": "text",
  "description": "text",
  "notify": true,
  "custom_alerts": {
    "email": [],
    "slack": [
      "text"
    ],
    "teams_webhook": []
  },
  "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",
  "threshold": {
    "type": "text",
    "min": 1,
    "max": 1
  },
  "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
delete
DELETE /api/v1/data/monitors?monitor_id=1 HTTP/1.1
Host: connect.<REGION>.decube.io
Accept: */*

No content

Monitor Validation & Constraints

This below 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.

Mode and scheduling rules

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

  • Scheduled monitors:

    • frequency is required.

    • row_creation is allowed to be specified to run this monitor as an incremental scan.

  • 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.

Frequency is one of:

  • Hourly: HourModeFrequency with frequency in { Hour1, Hour3, Hour6, Hour12 }.

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

  • Daily: DailyModeFrequency with frequency = Day1, requires time_of_day and timezone.

  • Weekly: WeeklyModeFrequency with frequency = Week1, requires time_of_day, day_of_week, and timezone.

  • Monthly: MonthlyModeFrequency with frequency = Month1, requires time_of_day, day_of_month, and timezone.

Additional 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; omitting it for weekly is rejected.

  • day_of_month is only valid for monthly frequency; providing it for other frequencies is rejected; omitting it for monthly is rejected. Prefer values 1–28 to avoid month-end edge cases.

  • time_of_day is an hour-of-day integer. The server validates its range.

Row creation modes

row_creation controls how rows are selected for computing metrics/tests:

  • AllRecordsMode (filter_mode = all_records): use all rows; no extra fields.

  • TimestampMode (filter_mode = timestamp): requires metric_column_id referencing a timestamp/datetime column in the asset. Optionally supports enable_smart_training.

  • SqlExpressionMode (filter_mode = sql_expression): requires sql_expression (a boolean filter SQL expression) and optional enable_smart_training.

Note: row_creation Enums values are case-sensitive, use lowercase values as shown above.

Validation notes:

  • metric_column_id must exist on the target asset and be a timestamp-like data type.

  • For sql_expression, the expression is validated for syntax against the underlying source via the configured connector. Invalid SQL will be rejected with a timeout/error code if the source cannot be reached within the internal timeout.

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: which shape to use per test type

Thresholds define the acceptable range or values for a test to pass. The shape of the threshold depends on the test_type. "auto_threshold" can be used where supported to let monitor automatically determine thresholds based on historical data.

The following shapes are supported for thresholds:

  • ValueThreshold — { "value": "..." }

  • ValuesThreshold — { "values": ["...", "..."] }

  • RangeThreshold — { "min": number|null, "max": number|null, "auto_threshold": boolean|null }

Mapping by test_type:

  • No threshold (ignored/rejected if provided):

    • not_null, is_unique, is_email, is_uuid, is_past_date, is_future_date, cardinality

  • Exact value(s):

    • value_is → ValueThreshold (single value)

    • value_in → ValuesThreshold (non-empty list of values)

  • Regex match:

    • regex_match → ValueThreshold where value is a valid regex for the source. The server compiles/validates it against the data source connector.

  • Percentages (0–100 constraints):

    • null_percentage, unique_percentage, zero_percentage, negative_percentage → RangeThreshold with min/max in [0, 100]

  • Numeric aggregations/ranges:

    • avg, min, max, sum, range, string_length → RangeThreshold

      • string_length applies to string columns; min/max are integer bounds.

General range rules:

  • At least one of min or max must be provided unless auto_threshold is true and supported by the server for that test type.

  • When both min and max are provided, min < max is required.

  • Percentage-based tests enforce 0–100 bounds.

On-demand compatible tests

  • Only a subset of tests can be run in on-demand mode. Typical on-demand-compatible tests include: most field-health tests such as null_percentage, not_null, is_unique, unique_percentage, avg, min, max, string_length, is_email, is_uuid, regex_match, value_is, value_in, is_past_date, is_future_date, zero_percentage, negative_percentage, sum, range.

  • Schema Drift (schema_drift family) and Job Failure (job_failure) are not supported as on-demand tests.

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 monitors and do not use thresholds, grouping, or row creation the same way as field-health tests. Many configuration fields are ignored for these.

  • Freshness/Volume monitors (dataset-level) threshold behavior are auto-learned depending on configuration and do not accept manual thresholds.

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": "Hour1|Hour3|Hour6|Hour12"}

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

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

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

  • Row creation unions:

    • 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:

    • Range: { "min"?: number, "max"?: number, "auto_threshold"?: boolean }

    • Value: { "value": string }

    • Values: { "values": string[] }

PreviousMonitorsNextACL

Last updated