Monitors

This document provides references to create or update the different type of monitors.

Please note that the sample queries below only show a subset of the fields available for brevity. You can use introspection to see all available fields.

📘

Adding Monitors Using the API vs Monitors as Code

This page is for setting up monitors using our API. If you are interesting in setting up monitors in a large environment using code, please see: Monitors as Code

Create or update monitors

Each monitor type is created or updated by calling a different GraphQL operation.

Below you can find some examples for Metric, Custom SQL and Job monitors.

🚧

Create vs Update

Please note the only difference between making a new monitor and updating one is providing the monitor uuid in the API call.

Create or Update Metric Monitors

Metric monitors can be updated via the API. Use cases include updating the description, changing the monitor interval or schedule, and modifying the monitor alert conditions

❗️

Bootstrapped Data

Please be aware that during the initial creation of Metric Monitors, Monte Carlo will attempt to backfill backfill a year's worth of metric history. We do this to generate a threshold more quickly. In order to minimize strain on your resources, there is a safeguard so that no more than 4 backfills are being run at any given time. After the initial collection, the monitors default to running one query twice a day.

mutation createOrUpdateMetricMonitor {
  createOrUpdateMetricMonitor(
    description: "Metric monitor for Row count on <table>"
    dwId: "<WAREHOUSE UUID>"
    dataSource: { type: TABLE, mcon: "<TABLE MCON>" }
    aggregate: {
      timeAxis: {
        field: "created_time"
        type: FIELD
      }
      by: DAY
    }
    collectionLagHours: 0
    scheduleConfig: {
      scheduleType: FIXED
      intervalMinutes: 1440
      startTime: "2024-11-27T01:00:00.000Z"
    }
    alertConditions: [
      {
        type: "threshold",
        operator: "AUTO",
        metric: "ROW_COUNT_CHANGE",
        fields: []
      }
    ],
  ){
    metricMonitor{
      uuid
      createdBy { email }
    }
  }
}
{
  "data": {
    "createOrUpdateMetricMonitor": {
      "metricMonitor": {
        "uuid": "932615cd-3296-45b8-8760-3cc618a57375",
        "createdBy": {
          "email": "[email protected]"
        }
      }
    }
  }
}

📘

Return uuid

It's important to return the uuid in the above command! If you need to update or change your rule, this is the id you will need to rerun this command.

Create or Update Custom SQL Monitors

Custom SQL monitors can be updated via the API. Use cases include updating the description, changing the monitor interval or schedule, and modifying the monitor alert conditions.

mutation createOrUpdateCustomSqlRule {
  createOrUpdateCustomSqlRule(
    description: "No error rows in table"
    dwId: "<WAREHOUSE UUID>"
    sql: "SELECT * FROM <table> WHERE <field> = 'error'"       
    scheduleConfig: {
      scheduleType: FIXED
      intervalMinutes: 1440
      startTime: "2024-11-27T01:00:00.000Z"
    }    
    alertCondition: {
      type: THRESHOLD,
      operator: GT,
      threshold: 0
    }
  ) {
    customRule {
      uuid
      creatorId
    }
  }
}
{
  "data": {
    "createOrUpdateCustomSqlRule": {
      "customRule": {
        "uuid": "d312568e-0651-4838-bac5-e3dd640ea911",
        "creatorId": "[email protected]"
      }
    }
  }
}
📘

Return uuid

It's important to return the uuid in the above command! If you need to update or change your rule, this is the id you will need to rerun this command.

Create or Update Job Monitors

Job monitors alert on job failures from one integration, such as an Airflow environment or a dbt connection. Use cases include alerting on failed jobs with a given tag, changing which failure types alert, and updating the audiences that are notified.

The job monitor operations are experimental, and the account must be using job monitors. Pass dryRun: true to validate a monitor without saving it.

First, find the integration the monitor will cover with getJobMonitorIntegrations:

query getJobMonitorIntegrations {
  getJobMonitorIntegrations {
    integrationType
    integrationUuid
    label
  }
}
{
  "data": {
    "getJobMonitorIntegrations": [
      {
        "integrationType": "AIRFLOW",
        "integrationUuid": "7b1e2f4a-5c3d-4e8f-9a6b-0c2d1e3f4a5b",
        "label": "prod-airflow"
      }
    ]
  }
}

Then create the monitor. This one alerts on failed Airflow jobs tagged tier:gold:

mutation createOrUpdateJobMonitor {
  createOrUpdateJobMonitor(
    description: "Gold tier Airflow job failures"
    integrationType: AIRFLOW
    integrationUuid: "<INTEGRATION UUID>"
    alertConditions: [{ condition: "etl_job_failure" }]
    assetSelection: {
      filters: [
        { type: JOB_TAG, jobTags: ["tier:gold"], jobTagsOperator: HAS_ANY }
      ]
    }
    jobMcons: []
    audiences: ["data-platform-oncall"]
    domainRestrictions: ["<DOMAIN UUID>"]
    priority: "P2"
  ) {
    jobMonitor {
      uuid
      name
    }
  }
}
{
  "data": {
    "createOrUpdateJobMonitor": {
      "jobMonitor": {
        "uuid": "5f0c3a9e-2b7d-4c61-8e4a-9d3b1f6a7c20",
        "name": "rule_k3x9p2qa"
      }
    }
  }
}
  • alertConditions: Non-dbt integrations accept etl_job_failure. dbt connections accept dbt_model_error, dbt_test_failure, dbt_test_warning, dbt_snapshot_error and dbt_seed_error. getJobAlertConditions lists the conditions for each integration type.
  • assetSelection and jobMcons: Select jobs by rule and by job MCON. Pass an empty selection and an empty list to cover every job in the integration.
  • domainRestrictions: The monitor only covers jobs in its domain.
🚧

Updates replace the whole definition

The integration can't change after the monitor is created. On update, assetSelection and jobMcons replace the stored values, and an empty selection or list clears them. Optional arguments you leave out, such as tags, alertGrouping and autoTriage, are cleared too. Send the full configuration every time.

The exceptions are the assetSelection joiners (filtersJoiner, exclusionsJoiner, tableFiltersJoiner, tableExclusionsJoiner) and tableExclusions, which keep their stored values when left out.

📘

Return uuid

It's important to return the uuid in the above command! If you need to update or change your monitor, this is the id you will need to rerun this command.

Listing Custom SQL Monitors

If you would like to view a Custom SQL monitor after the fact, you can always run the following getCustomRule query with the uuid that was returned from the create mutation:

query {
  getCustomRule(
    ruleId: "<rule_uuid>"
  ) {
    intervalMinutes
    comparisons {
      comparisonType
      metric
      operator
      threshold
    }
    description
    timezone
    startTime
    customSql
  }
}
{
  "data": {
    "getCustomRule": {
      "intervalMinutes": 1440,
      "comparisons": [
        {
          "comparisonType": "THRESHOLD",
          "metric": "custom_metric_<rule_uuid>",
          "operator": "GT",
          "threshold": 0
        }
      ],
      "description": "Sample description",
      "timezone": "UTC",
      "startTime": "2021-06-30T19:00:00+00:00",
      "customSql": "<sql_query>"
    }
  }
}

If you are updating an existing SQL rule, you can find a list of your existing rule uuids by running:

query {
  getCustomRules (
    first: 5
    ruleType: "CUSTOM_SQL"
  ) {
    edges {
      node {
        uuid
        creatorId
        createdTime
        description
        isDeleted
        entities
        scheduleConfig {
          intervalMinutes
          startTime
        }
      }
    }
  }
}
{
  "errors": <There might be some errors here. For the most part, you can ignore!>,
  "data": {
    "getCustomRules": {
      "edges": [
        {
          "node": {
            "uuid": "<this is the uuid you are looking for>",
            "creatorId": "<email>",
            "createdTime": "2021-06-29T20:01:22.427007+00:00",
            "description": "Sample Description",
            "isDeleted": false,
            "entities": [
             "<full_table_id>"
            ],
            "scheduleConfig": {
              "intervalMinutes": 1440,
              "startTime": "2021-06-30T19:00:00+00:00"
            }
          }
        },
    ….
      ]
    }
  }
}

This query accepts the following arguments to narrow in on the rule you are looking for: before, after, first, last, and ruleType. Once you have found the necessary uuid, you can follow step 2 above to update it by adding the uuid argument in the call.

Basic Monitor Information Using getMonitors:

Using the getMonitors query, you can obtain general information about the monitor, such as monitor type, description, schedules, etc. There are a huge amount of parameters to specify the query and result fields to choose from here, so there are plenty of use cases for this query. See the full list of results here in the API Reference Guide.

query getMonitors($alertedOnly: Boolean,
  $consolidatedStatusTypes: [ConsolidatedMonitorStatusType],
  $domainId: UUID,
  $includeOotbMonitors: Boolean,
  $labels: [String],
  $limit: Int,
  $mcons: [String],
  $monitorTypes: [UserDefinedMonitors],
  $tags: [TagKeyValuePairInput!],
  $uuids: [String]) {
  getMonitors(
    consolidatedStatusTypes: $consolidatedStatusTypes,
    domainId: $domainId,
    includeOotbMonitors: $includeOotbMonitors,
    labels: $labels,
    limit: $limit,
    mcons: $mcons,
    monitorTypes: $monitorTypes,
    tags: $tags,
    uuids: $uuids{
    uuid
    monitorType
    name
    description
    prevExecutionTime
    dataQualityDimension
    alertIds
    createdTime
    consolidatedMonitorStatus
  }
}

Table Monitor Coverage

A Table monitor selects tables by rules (warehouse, databases, schemas and filters), so the API doesn't list the tables it covers on the monitor itself:

  • entityMcons is always empty for Table monitors, and the monitors field on getTables doesn't include them. To find the monitors on a table, pass its MCON to getMonitors as mcons.
  • To see which tables each Table monitor covers, use the ASSETS and ASSET_IDS columns of the Monitors data export. They list up to 1,000 tables per monitor. ASSET_COUNT has the full count.
  • getTableMonitor returns a monitor's selection rules: its warehouseUuid and assetSelection.
  • getTableMonitorCoverage returns tablesAtRisk: only the tables that this monitor alone covers, which would become unmonitored if it were deleted. It isn't the monitor's full coverage.

Monitor Results:

Using the getMetricsV4 query, you can obtain the metadata results that are collected from monitor runs, as well as the thresholds that are in-tandem with each result.

query getMetricsV4($endTime: DateTime, $first: Int, $metricName: String!, $metricsFilter: MetricsFilter!, $startTime: DateTime!, $deduplicateValues: Boolean) {
  getMetricsV4(
    endTime: $endTime
    first: $first
    metricName: $metricName
    metricsFilter: $metricsFilter
    startTime: $startTime
    deduplicateValues: $deduplicateValues
  ) {
    metrics {
      field
      fullTableId
      jobExecutionUuid
      measurementTimestamp
      metric
      thresholds {
      upper
      lower
      }
      timestamp
      value
    }
    metricsJson
  }
}

What to pass in metricsFilter:

  • Metric monitors: the monitor's UUID as monitorId.
  • Table monitors (freshness and volume): leave out monitorId and pass the table's mcon. A Table monitor's UUID isn't a valid monitorId and returns Invalid monitor_id.

For Table monitor volume, query total_row_count. There's no stored total_row_count_change series, so that name returns nothing. Thresholds come back on each datapoint in thresholds.

Each datapoint has timestamp and measurementTimestamp. For metric monitors, timestamp is the period the data covers and measurementTimestamp is when it was measured. For Table monitors, both are the measurement time. To get the most recent result, set startTime a few days back, leave out endTime, and pass first: 1. For a segmented monitor, make one call per segment.

📘

Datapoints are removed 90 days after they're measured, including backfilled datapoints, whatever period they cover.

Monitor Run Executions:

Using the getJobExecutions query, you can see each run of the monitor with details such as a start and end timestamp, success/failure, and any reasons for failures.

query getJobExecutions(
  $customRuleUuid: String,
  $monitorUuid: String,
  $historyDays: Int,
  $cursor: String,
  $first: Int) {
  getJobExecutions(
    customRuleUuid: $customRuleUuid
    monitorUuid: $monitorUuid
    historyDays: $historyDays
    after: $cursor
    first: $first
  ) {
    pageInfo {
      endCursor
      hasNextPage
      __typename
    }
    edges {
      node {
        jobExecutionUuid
        startTime
        endTime
        status
        runEvaluatedRowCount
        runBreachedRowCount
        exceptions
        exceptionsDetail {
          type
          description
          sqlQuery
        }
      }
    }
  }
}
📘

Table monitors

Table monitors don't have runs of their own: they evaluate the metadata Monte Carlo collects from the warehouse, so getJobExecutions returns the warehouse's collection runs for them.

For a Table monitor's own state, use prevExecutionTime and consolidatedMonitorStatus from getMonitors.

Monitor Failure Rates using getJobExecutions

Validation and Custom SQL monitors record the evaluated row count — the total population behind each result — alongside the rows that breached. Both land on each run, clean or breaching, and getJobExecutions returns them per run as runEvaluatedRowCount and runBreachedRowCount.

📘

To capture runEvaluatedRowCount, make sure it's enabled for your account — and that a baseline query is defined on your Custom SQL monitor(s). See Measuring evaluated rows for validation and Custom SQL monitors.

Together they support custom aggregations and reporting: a failure rate per run, a trend over a period, or a single figure across monitors for a table, domain, or data product.

query GetRunRowCounts($monitorUuid: String, $historyDays: Int) {
  getJobExecutions(
    monitorUuid: $monitorUuid
    historyDays: $historyDays
  ) {
    edges {
      node {
        jobExecutionUuid
        startTime
        endTime
        status
        runEvaluatedRowCount
        runBreachedRowCount
      }
    }
  }
}
{
  "monitorUuid": "<monitor_uuid>",
  "historyDays": 5
}
{
  "data": {
    "getJobExecutions": {
      "edges": [
        {
          "node": {
            "jobExecutionUuid": "3f8a1c40-9b72-4e15-8d63-1a5e7c204b98",
            "startTime": "2026-09-21T09:00:00.000000+00:00",
            "endTime": "2026-09-21T09:00:04.120000+00:00",
            "status": "SUCCESS",
            "runEvaluatedRowCount": 402118,
            "runBreachedRowCount": 6
          }
        },
        {
          "node": {
            "jobExecutionUuid": "c20d7e55-1f84-42a9-b370-6d9b8e31af22",
            "startTime": "2026-09-20T09:00:00.000000+00:00",
            "endTime": "2026-09-20T09:00:03.880000+00:00",
            "status": "SUCCESS",
            "runEvaluatedRowCount": 401904,
            "runBreachedRowCount": 0
          }
        },
        {
          "node": {
            "jobExecutionUuid": "9e4b06a1-73c8-4d2f-95ae-2c1f4d80b7e6",
            "startTime": "2026-09-19T09:00:00.000000+00:00",
            "endTime": "2026-09-19T09:00:04.050000+00:00",
            "status": "SUCCESS",
            "runEvaluatedRowCount": 401677,
            "runBreachedRowCount": 214
          }
        }
      ]
    }
  }
}

Run Monitors On Demand

Use runMonitors to run one or more monitors outside their schedule. It detects each monitor's type and routes the run accordingly, so a single call can mix Custom SQL, Validation, metric, and comparison monitors. Table, bulk, and job monitors can't be run on demand. If the list includes one, the whole call fails and nothing runs.

mutation {
  runMonitors(monitorUuids: ["<monitor_uuid>", "<monitor_uuid>"]) {
    success
    manualMonitorExecutionUuids
  }
}

manualMonitorExecutionUuids has one entry per monitor, in the order you sent them. Metric and comparison monitors get an execution UUID. Custom SQL and Validation monitors are queued too, but their entry is null, which doesn't mean the run failed. Poll an execution UUID with getManualMonitorExecutionStatus for its status and whether it breached.

📘

runSqlRule runs one Custom SQL or Validation monitor and accepts runtime variables. Use runMonitors to run several monitors, or monitors of different types, in one call.

Data Profiler Results

The results on an asset's Data Profiler tab are available from getDataProfilerWidgetData. The field statistics come from the FIELD_PROFILE_TABLE_V2 widget:

query DataProfile($mcon: String!, $limit: Int!, $offset: Int!) {
  getDataProfilerWidgetData(
    request: {
      dataset: { mcon: $mcon }
      widgetType: FIELD_PROFILE_TABLE_V2
      limit: $limit
      offset: $offset
    }
  ) {
    dataFrame
    totalRowCount
    limit
    offset
    responseMetadata {
      queryResponseFields {
        name
        sqlAlias
        displayName
      }
    }
  }
}

Other values for widgetType:

  • NUMERIC_DESCRIPTIVE_STATS: mean, median, and similar statistics for numeric fields
  • TIMESTAMP_HISTOGRAM
  • DISCRETE: returns raw values from your tables, so it's only available when data sampling is enabled for the warehouse and table, and you have permission to view sampled data

Results are paged with limit (default 50) and offset. With FIELD_PROFILE_TABLE_V2 and DISCRETE, pass fieldName to return a single field.

Details and edge cases

getJobExecutions for monitors with variables. A monitor that uses variables returns one entry per scheduled run, not one per combination of variable values.

getJobExecutions entries for Table monitors. For a Table monitor, getJobExecutions returns the warehouse's collection runs since the monitor was created: mostly the same jobExecutionUuid values for every Table monitor on that warehouse, plus any failed runs of that monitor. Entries continue while a Table monitor is paused, because collection keeps running.


Did this page help you?