Monitor runs
Trigger Data Quality V2 monitors on demand and read the status and results of their runs
Every time a monitor executes, Decube records a run. Scheduled monitors create runs on their own schedule. Monitors with a Manual schedule run only when you trigger them — from the UI or from this API. This is how you run a check straight after a pipeline loads a table, rather than waiting for the next scheduled slot.
Runs are asynchronous. You trigger a run, receive its run_id, and check the run until it finishes.
Trigger a run
Start an on-demand run of a monitor.
Successful Response
Validation Error
POST /api/v1/data/data_quality/monitors/trigger HTTP/1.1
Host: connect.<REGION>.decube.io
Content-Type: application/json
Accept: */*
Content-Length: 16
{
"monitor_id": 1
}{
"run_id": 1
}A trigger succeeds only when all of these are true.
The monitor's active configuration uses the
manualschedule.The monitor is enabled and has no
invalid_reason.No run for the active configuration is already queued or running.
Check a run
Returns the timing and result of one run. This works for scheduled runs as well as triggered ones.
Get the status and result of one monitor run.
Successful Response
Validation Error
GET /api/v1/data/data_quality/monitors/runs/details?run_id=1 HTTP/1.1
Host: connect.<REGION>.decube.io
Accept: */*
{
"id": 1,
"scheduled_at": "2026-01-01T00:00:00.000Z",
"executed_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"result": {
"state": "text"
}
}scheduled_at
When the run was due, or when you triggered it
executed_at
When the run started. null while queued.
ended_at
When the run finished. null until it does.
result
The run's state and, once finished, its outcome
Reading the result
result.state tells you where the run is:
queuedandrunning— the run hasn't finished yet. Check again later.completed— the run finished and Decube evaluated the result. Readresult.evaluation.outcome.errored— the run couldn't finish. Readresult.reason.
For a completed run, result.evaluation.outcome is one of:
passed
The check passed. evidence shows what Decube measured.
failed
The check failed and Decube raised an incident. evidence shows what Decube measured.
skipped_no_data
The scanned rows were empty, so there was nothing to check.
skipped_no_prev_data
The check compares against a previous period that isn't available. reason is first_period or previous_period_no_data.
For an errored run, result.reason is one of:
connection_failed
Decube couldn't connect to the source
query_failed
The monitor's query failed on the source
timeout
The query didn't finish in time
schedule_lag_exceeded
The run couldn't start or finish within 25 minutes of its scheduled time
lease_expired
The run stopped reporting progress and Decube marked it as errored
query_result_invalid
The query returned a result Decube couldn't evaluate
source_not_found
The source no longer exists in Decube
primary_asset_not_found
The table, column, or source the monitor checks no longer exists
timestamp_column_not_found
The timestamp column the monitor uses no longer exists
primary_asset_incompatible_type
The monitored column's data type no longer suits the monitor type
timestamp_col_incompatible_type
The timestamp column's data type is no longer a date or timestamp
internal
An error inside Decube. Contact support@decube.io if it repeats.
Wait for a run to finish
Poll the run every 15 to 30 seconds until result.state is completed or errored. Decube marks a run as errored if it doesn't finish within 25 minutes of its scheduled time, so a 30-minute limit on your polling loop is enough.
Examples shows how to use this to fail a pipeline step when a check fails.
List run history
List the runs of a monitor. Exclude configuration_id to cover the active version.
251Successful Response
Validation Error
GET /api/v1/data/data_quality/monitors/runs?monitor_id=1 HTTP/1.1
Host: connect.<REGION>.decube.io
Accept: */*
{
"items": [
{
"id": 1,
"scheduled_at": "2026-01-01T00:00:00.000Z",
"executed_at": "2026-01-01T00:00:00.000Z",
"ended_at": "2026-01-01T00:00:00.000Z",
"result": {
"state": "text"
}
}
],
"page_number": 1,
"page_size": 1
}monitor_id
Yes
configuration_id
No
Lists runs for this version instead of the active one
page_size
No
Default 25, maximum 100
page_number
No
Default 1
Each item has the same shape as Check a run. Runs from earlier versions don't appear unless you pass their configuration_id — call Get a monitor to list a monitor's versions.
Frequently Asked Questions
Can I trigger a monitor that runs on a schedule?
No. Only monitors on a manual schedule accept triggers. To run a scheduled check on demand, create a separate monitor with a manual schedule, or update the configuration to manual. Changing the schedule is destructive, so it creates a new version.
Why does my trigger return 400?
Check the three conditions in Trigger a run. The most common causes are a monitor that isn't on a manual schedule, and a previous run that is still queued or running.
Does a triggered run raise incidents and alerts?
Yes. A triggered run evaluates the same way as a scheduled run. A failure raises an incident, joins the open case, and goes through your alert rules.
Last updated