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

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

Trigger Monitor Run

post

Start an on-demand run of a monitor.

Body
monitor_idintegerRequired
Responses
200

Successful Response

application/json
run_idintegerRequired
post/data_quality/monitors/trigger
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 manual schedule.

  • The monitor is enabled and has no invalid_reason.

  • No run for the active configuration is already queued or running.

To run a monitor from your pipeline, create it with "schedule": { "frequency": "manual" }. Every monitor type supports a manual schedule except freshness_sla and volume. Field Health monitors on a manual schedule must use "scan_method": { "type": "full_table_scan" }.

Check a run

Returns the timing and result of one run. This works for scheduled runs as well as triggered ones.

Get Monitor Run

get

Get the status and result of one monitor run.

Query parameters
run_idintegerRequired
Responses
200

Successful Response

application/json
idintegerRequired
scheduled_atstring · date-timeRequired
executed_atstring · date-time · nullableRequired
ended_atstring · date-time · nullableRequired
resultone ofRequired
or
or
or
get/data_quality/monitors/runs/details
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"
  }
}
Field
Meaning

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:

  • queued and running — the run hasn't finished yet. Check again later.

  • completed — the run finished and Decube evaluated the result. Read result.evaluation.outcome.

  • errored — the run couldn't finish. Read result.reason.

For a completed run, result.evaluation.outcome is one of:

Outcome
Meaning

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:

Reason
Meaning

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 Monitor Runs

get

List the runs of a monitor. Exclude configuration_id to cover the active version.

Query parameters
monitor_idintegerRequired
configuration_idinteger · nullableOptional
page_sizeinteger · min: 1 · max: 100OptionalDefault: 25
page_numberinteger · min: 1 · max: 100000OptionalDefault: 1
Responses
200

Successful Response

application/json
page_numberintegerRequired
page_sizeintegerRequired
get/data_quality/monitors/runs
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
}
Parameter
Required
Notes

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