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 CodeThis 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.
- CreateOrUpdateValidation: Create or update a Validation monitor
- CreateOrUpdateMetricMonitor: Create or update a Metric monitor
- CreateOrUpdateCustomSqlRule: Create or update a Custom SQL monitor
- CreateOrUpdateComparisonRule: Create or update a Comparison monitor
- CreateOrUpdateQueryPerfRule: Create or update a Query Performance monitor
- CreateOrUpdateJsonSchemaMonitor: Create or update a JSON Schema monitor
- CreateOrUpdateJobMonitor: Create or update a Job monitor
Below you can find some examples for Metric, Custom SQL and Job monitors.
Create vs UpdatePlease note the only difference between making a new monitor and updating one is providing the monitor
uuidin 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 DataPlease 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 uuidIt's important to return the
uuidin 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 uuidIt's important to return the
uuidin 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 acceptetl_job_failure. dbt connections acceptdbt_model_error,dbt_test_failure,dbt_test_warning,dbt_snapshot_erroranddbt_seed_error. getJobAlertConditions lists the conditions for each integration type.assetSelectionandjobMcons: 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 definitionThe integration can't change after the monitor is created. On update,
assetSelectionandjobMconsreplace the stored values, and an empty selection or list clears them. Optional arguments you leave out, such astags,alertGroupingandautoTriage, are cleared too. Send the full configuration every time.The exceptions are the
assetSelectionjoiners (filtersJoiner,exclusionsJoiner,tableFiltersJoiner,tableExclusionsJoiner) andtableExclusions, which keep their stored values when left out.
Return uuidIt's important to return the
uuidin 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:
entityMconsis always empty for Table monitors, and themonitorsfield ongetTablesdoesn't include them. To find the monitors on a table, pass its MCON to getMonitors asmcons.- To see which tables each Table monitor covers, use the
ASSETSandASSET_IDScolumns of the Monitors data export. They list up to 1,000 tables per monitor.ASSET_COUNThas the full count. - getTableMonitor returns a monitor's selection rules: its
warehouseUuidandassetSelection. - 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
monitorIdand pass the table'smcon. A Table monitor's UUID isn't a validmonitorIdand returnsInvalid 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 monitorsTable monitors don't have runs of their own: they evaluate the metadata Monte Carlo collects from the warehouse, so
getJobExecutionsreturns the warehouse's collection runs for them.For a Table monitor's own state, use
prevExecutionTimeandconsolidatedMonitorStatusfrom getMonitors.
Monitor Failure Rates using getJobExecutions
getJobExecutionsValidation 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.
runSqlRuleruns one Custom SQL or Validation monitor and accepts runtime variables. UserunMonitorsto 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 fieldsTIMESTAMP_HISTOGRAMDISCRETE: 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.
Updated 6 days ago
