Discover the New Soda AI – MCP, Autopilot, CLI |
Learn More
Ctrlk
Soda CloudBook a demo
slack
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Metric Monitors

Soda Cloud API Metric Monitor Endpoints

List the monitors of a dataset

get
/api/v1/monitors

This endpoint returns the metric monitors of a V4 dataset in your organization's Soda Cloud account, one row per monitor, together with the outcome of each monitor's most recent result. Dataset metric monitors, column metric monitors and custom SQL monitors come back in the same flat list, most critical first; use monitorType to ask for only one of them. For the history of one monitor's results, use GET /api/v1/monitors/{monitorId}/results.

This GET is a paginated API that uses the following parameters to request specific details:

  • datasetId: Required. The id of the dataset whose monitors to list, which you can find in the URL of the dataset page in Soda Cloud.

  • monitorType: Optionally, use this parameter to collect only the monitors of one type, as returned in monitorType: dataset for the monitors that watch the dataset as a whole, column for the ones that watch a single column, and customSql for the ones that watch the result of a custom SQL query. Defaults to all three.

  • metricType: Optionally, use this parameter to collect only the monitors that watch one metric, such as rowCount.

  • columnName: Optionally, use this parameter to collect only the monitors that watch one column. The name must match exactly.

  • size: Supply an integer value between 1 and 200, inclusive. The default value is 50.

  • page: Supply an integer value. The default value is 0.

Results are sorted with the most critical monitors first, then by the time of their most recent result, newest first.

A group-by monitor comes back as its group parent monitor plus one group member per group. They share a groupIdentity; the group parent monitor is the row that carries groupByColumns and groupMembersCount.

Authorization

Only users with View dataset permission can list a dataset's monitors. Soda Cloud Admins have access to all datasets. See Manage dataset roles for more information.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Metric Monitors

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Query parameters
columnNamestringOptional
datasetIdstringRequired
metricTypeobject · enumOptionalPossible values:
monitorTypeobject · enumOptionalPossible values:
pageinteger · int32Optional
sizeinteger · int32Optional
Responses
200

Successful response

application/json
firstbooleanRequired
lastbooleanRequired
numberinteger · int32Required
sizeinteger · int32Required
totalElementsinteger · int32Required
totalPagesinteger · int32Required
get/api/v1/monitors
GET /api/v1/monitors?datasetId=text HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "content": [
    {
      "anomalousGroupMembersCount": 1,
      "columnName": "text",
      "evaluationStatus": "pass",
      "groupByColumnValues": [
        {
          "columnName": "text",
          "columnValue": {}
        }
      ],
      "groupByColumns": [
        {
          "columnName": "text",
          "excludedValues": [
            "text"
          ]
        }
      ],
      "groupIdentity": "text",
      "groupMembersCount": 1,
      "hasNotificationRules": true,
      "isEnabled": true,
      "lastDataTimestamp": "2026-01-01T00:00:00.000Z",
      "metricType": "schema",
      "monitorId": "text",
      "monitorName": "text",
      "monitorType": "dataset"
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}

Create a metric monitor

post
/api/v1/monitors

This endpoint allows you to create a dataset metric monitor, a column metric monitor or a custom SQL monitor on a V4 dataset in your organization's Soda Cloud account. Send the dataset in datasetId and the monitor under exactly one of datasetMetricMonitor, columnMetricMonitor or customSqlMetricMonitor.

The dataset needs metric monitoring switched on before it can take monitors. Switch it on with POST /api/v1/datasets/{datasetId} and the metricMonitoring block; without it this endpoint answers 400.

A dataset has one dataset metric monitor per metric type, such as row count or freshness. Creating a type the dataset already has answers 400 with the id of the existing monitor; change that one with POST /api/v1/monitors/{monitorId} instead.

The response returns the new monitor with its monitorId, which the other /api/v1/monitors endpoints take.

Authorization

Only users with Manage contracts permission can create monitors. Soda Cloud Admins can create monitors for all datasets. See Manage dataset roles for more information.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Metric Monitors

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
datasetIdstringRequired
Responses
200

Successful response

application/json
datasetIdstringRequired
monitorIdstringRequired

The id of the monitor. Column and custom SQL monitor objects repeat it as checkId.

post/api/v1/monitors
POST /api/v1/monitors HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 1110

{
  "columnMetricMonitor": {
    "columnName": "text",
    "configuration": {
      "groupByColumns": [
        {
          "columnName": "text",
          "excludedValues": [
            "text"
          ]
        }
      ],
      "exclusionZones": [
        {
          "lowerLimit": 1,
          "singleValue": true,
          "upperLimit": 1
        }
      ],
      "isEnabled": true,
      "isSamplingEnabled": true,
      "sensitivity": 1,
      "thresholdStrategy": {
        "isLowerBoundEnabled": true,
        "isUpperBoundEnabled": true
      },
      "validRange": {
        "max": 1,
        "min": 1
      }
    },
    "metricType": "missingPercentage"
  },
  "customSqlMetricMonitor": {
    "columnName": "text",
    "configuration": {
      "groupByColumnNames": [
        "text"
      ],
      "resultMetric": "text",
      "sqlQuery": "text",
      "exclusionZones": [
        {
          "lowerLimit": 1,
          "singleValue": true,
          "upperLimit": 1
        }
      ],
      "isEnabled": true,
      "isSamplingEnabled": true,
      "sensitivity": 1,
      "thresholdStrategy": {
        "isLowerBoundEnabled": true,
        "isUpperBoundEnabled": true
      },
      "validRange": {
        "max": 1,
        "min": 1
      }
    },
    "monitorName": "text"
  },
  "datasetId": "text",
  "datasetMetricMonitor": {
    "configuration": {
      "exclusionZones": [
        {
          "lowerLimit": 1,
          "singleValue": true,
          "upperLimit": 1
        }
      ],
      "isEnabled": true,
      "isSamplingEnabled": true,
      "sensitivity": 1,
      "thresholdStrategy": {
        "isLowerBoundEnabled": true,
        "isUpperBoundEnabled": true
      },
      "validRange": {
        "max": 1,
        "min": 1
      }
    },
    "metricType": "rowCount"
  }
}
{
  "columnMetricMonitor": {
    "checkId": "text",
    "columnName": "text",
    "configuration": {
      "groupByColumns": [
        {
          "columnName": "text",
          "excludedValues": [
            "text"
          ]
        }
      ],
      "exclusionZones": [
        {
          "lowerLimit": 1,
          "singleValue": true,
          "upperLimit": 1
        }
      ],
      "isEnabled": true,
      "isSamplingEnabled": true,
      "sensitivity": 1,
      "thresholdStrategy": {
        "isLowerBoundEnabled": true,
        "isUpperBoundEnabled": true
      },
      "validRange": {
        "max": 1,
        "min": 1
      }
    },
    "metricType": "missingPercentage"
  },
  "customSqlMetricMonitor": {
    "checkId": "text",
    "columnName": "text",
    "configuration": {
      "groupByColumnNames": [
        "text"
      ],
      "resultMetric": "text",
      "sqlQuery": "text",
      "exclusionZones": [
        {
          "lowerLimit": 1,
          "singleValue": true,
          "upperLimit": 1
        }
      ],
      "isEnabled": true,
      "isSamplingEnabled": true,
      "sensitivity": 1,
      "thresholdStrategy": {
        "isLowerBoundEnabled": true,
        "isUpperBoundEnabled": true
      },
      "validRange": {
        "max": 1,
        "min": 1
      }
    },
    "monitorName": "text"
  },
  "datasetId": "text",
  "datasetMetricMonitor": {
    "configuration": {
      "exclusionZones": [
        {
          "lowerLimit": 1,
          "singleValue": true,
          "upperLimit": 1
        }
      ],
      "isEnabled": true,
      "isSamplingEnabled": true,
      "sensitivity": 1,
      "thresholdStrategy": {
        "isLowerBoundEnabled": true,
        "isUpperBoundEnabled": true
      },
      "validRange": {
        "max": 1,
        "min": 1
      }
    },
    "metricType": "rowCount"
  },
  "monitorId": "text"
}

Create metric monitors in bulk

post
/api/v1/monitors/actions/bulkCreate

This endpoint allows you to create up to 100 metric monitors in one call: dataset metric monitors, column metric monitors or custom SQL monitors, on one or more V4 datasets. Each entry of monitors is the body of POST /api/v1/monitors: the dataset in datasetId and the monitor under exactly one of datasetMetricMonitor, columnMetricMonitor or customSqlMetricMonitor.

Entries are handled one by one: an entry that fails does not stop the others, and nothing already created is undone. The response returns the new monitors in createdMonitors and every entry that failed, with its error, in failedMonitors.

Authorization

Only users with Manage contracts permission on a dataset can create monitors on it. Soda Cloud Admins can create monitors for all datasets. See Manage dataset roles for more information.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Metric Monitors

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
Responses
200

Successful response

application/json
post/api/v1/monitors/actions/bulkCreate
POST /api/v1/monitors/actions/bulkCreate HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 1125

{
  "monitors": [
    {
      "columnMetricMonitor": {
        "columnName": "text",
        "configuration": {
          "groupByColumns": [
            {
              "columnName": "text",
              "excludedValues": [
                "text"
              ]
            }
          ],
          "exclusionZones": [
            {
              "lowerLimit": 1,
              "singleValue": true,
              "upperLimit": 1
            }
          ],
          "isEnabled": true,
          "isSamplingEnabled": true,
          "sensitivity": 1,
          "thresholdStrategy": {
            "isLowerBoundEnabled": true,
            "isUpperBoundEnabled": true
          },
          "validRange": {
            "max": 1,
            "min": 1
          }
        },
        "metricType": "missingPercentage"
      },
      "customSqlMetricMonitor": {
        "columnName": "text",
        "configuration": {
          "groupByColumnNames": [
            "text"
          ],
          "resultMetric": "text",
          "sqlQuery": "text",
          "exclusionZones": [
            {
              "lowerLimit": 1,
              "singleValue": true,
              "upperLimit": 1
            }
          ],
          "isEnabled": true,
          "isSamplingEnabled": true,
          "sensitivity": 1,
          "thresholdStrategy": {
            "isLowerBoundEnabled": true,
            "isUpperBoundEnabled": true
          },
          "validRange": {
            "max": 1,
            "min": 1
          }
        },
        "monitorName": "text"
      },
      "datasetId": "text",
      "datasetMetricMonitor": {
        "configuration": {
          "exclusionZones": [
            {
              "lowerLimit": 1,
              "singleValue": true,
              "upperLimit": 1
            }
          ],
          "isEnabled": true,
          "isSamplingEnabled": true,
          "sensitivity": 1,
          "thresholdStrategy": {
            "isLowerBoundEnabled": true,
            "isUpperBoundEnabled": true
          },
          "validRange": {
            "max": 1,
            "min": 1
          }
        },
        "metricType": "rowCount"
      }
    }
  ]
}
{
  "createdMonitors": [
    {
      "columnMetricMonitor": {
        "checkId": "text",
        "columnName": "text",
        "configuration": {
          "groupByColumns": [
            {
              "columnName": "text",
              "excludedValues": [
                "text"
              ]
            }
          ],
          "exclusionZones": [
            {
              "lowerLimit": 1,
              "singleValue": true,
              "upperLimit": 1
            }
          ],
          "isEnabled": true,
          "isSamplingEnabled": true,
          "sensitivity": 1,
          "thresholdStrategy": {
            "isLowerBoundEnabled": true,
            "isUpperBoundEnabled": true
          },
          "validRange": {
            "max": 1,
            "min": 1
          }
        },
        "metricType": "missingPercentage"
      },
      "customSqlMetricMonitor": {
        "checkId": "text",
        "columnName": "text",
        "configuration": {
          "groupByColumnNames": [
            "text"
          ],
          "resultMetric": "text",
          "sqlQuery": "text",
          "exclusionZones": [
            {
              "lowerLimit": 1,
              "singleValue": true,
              "upperLimit": 1
            }
          ],
          "isEnabled": true,
          "isSamplingEnabled": true,
          "sensitivity": 1,
          "thresholdStrategy": {
            "isLowerBoundEnabled": true,
            "isUpperBoundEnabled": true
          },
          "validRange": {
            "max": 1,
            "min": 1
          }
        },
        "monitorName": "text"
      },
      "datasetId": "text",
      "datasetMetricMonitor": {
        "configuration": {
          "exclusionZones": [
            {
              "lowerLimit": 1,
              "singleValue": true,
              "upperLimit": 1
            }
          ],
          "isEnabled": true,
          "isSamplingEnabled": true,
          "sensitivity": 1,
          "thresholdStrategy": {
            "isLowerBoundEnabled": true,
            "isUpperBoundEnabled": true
          },
          "validRange": {
            "max": 1,
            "min": 1
          }
        },
        "metricType": "rowCount"
      },
      "monitorId": "text"
    }
  ],
  "failedMonitors": [
    {
      "datasetId": "text",
      "errorCode": "text",
      "errorMessage": "text",
      "index": 1
    }
  ]
}

Submit the same feedback on several monitor results

post
/api/v1/monitors/results/actions/feedback

This endpoint gives up to 100 monitor results the same feedback in one call, which is what you want after a planned event such as a migration or a backfill made the anomaly detection model flag a whole stretch of history.

It is all or nothing: if one monitor result does not exist, sits on a dataset you may not manage, belongs to a check that is not a metric monitor, or belongs to a monitor on a V3 dataset, the call fails and none of them are written.

Submitting feedback replaces the feedback the results already carried. Both result listings return it again under feedback, after a short delay.

The body takes the following fields:

  • resultIds: The monitor results that all get the same feedback. At least one, at most 100.

  • feedback: The same body as Submit feedback on a monitor result.

Authorization

Only users with Manage contracts permission can submit feedback. Soda Cloud Admins can submit feedback on all monitor results. A result on a dataset the user may not view is reported as not found. See Manage dataset roles for more information.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Metric Monitors

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
resultIdsstring[]Required

The monitor results that all get the same feedback. Every id must exist and belong to a metric monitor of a V4 dataset, otherwise nothing is written.

Responses
200

Successful response

application/json
resultIdsstring[]Required

The monitor results that now carry the feedback, each once, in the order they were requested.

post/api/v1/monitors/results/actions/feedback
POST /api/v1/monitors/results/actions/feedback HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 154

{
  "feedback": {
    "freeTextReason": "text",
    "isCorrectlyClassified": true,
    "reason": "expectedDailySeasonality",
    "skipMeasurements": "previous"
  },
  "resultIds": [
    "text"
  ]
}
{
  "feedback": {
    "freeTextReason": "text",
    "isCorrectlyClassified": true,
    "reason": "expectedDailySeasonality",
    "skipMeasurements": "previous",
    "submittedAt": "2026-01-01T00:00:00.000Z"
  },
  "resultIds": [
    "text"
  ]
}

Submit feedback on a monitor result

post
/api/v1/monitors/results/{resultId}/feedback

This endpoint tells the anomaly detection model behind a metric monitor what it got wrong, or which measurements it must leave out of its training. Use it on the results of metric monitors of V4 datasets: the result ids come from GET /api/v1/checks/{checkId}/results called with the monitorId, or from recentResults of GET /api/v1/monitors. A result of any other check, or of a monitor on a V3 dataset, is rejected with a 400.

Submitting feedback replaces the feedback the result already carried. Both result listings return it again under feedback, after a short delay.

The body takes the following fields:

  • isCorrectlyClassified: Whether the model classified this result correctly. Leave it out when you only want to skip measurements.

  • reason: Why the classification was wrong. Required when isCorrectlyClassified is false.

  • freeTextReason: The reason in your own words. Required when reason is other.

  • skipMeasurements: Which measurements the model must leave out when it trains on the monitor's history. Required when isCorrectlyClassified is left out.

Authorization

Only users with Manage contracts permission can submit feedback. Soda Cloud Admins can submit feedback on all monitor results. A result on a dataset the user may not view is reported as not found. See Manage dataset roles for more information.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Metric Monitors

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
resultIdstringRequired
Body
freeTextReasonstringOptional

The reason in your own words. Required when reason is other.

isCorrectlyClassifiedbooleanOptional

Whether the anomaly detection model classified this result correctly. Leave it out when you only want to skip measurements without judging the classification.

reasonobject · enumOptional

Why the classification was wrong. Required when isCorrectlyClassified is false.

Possible values:
skipMeasurementsobject · enumOptional

Which measurements the anomaly detection model must leave out when it trains on the monitor's history. Required when isCorrectlyClassified is left out.

Possible values:
Responses
200

Successful response

application/json
monitorIdstringRequired

The monitor the result belongs to. Use it in GET /api/v1/checks/{checkId}/results.

resultIdstringRequired
post/api/v1/monitors/results/{resultId}/feedback
POST /api/v1/monitors/results/{resultId}/feedback HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "freeTextReason": "text",
  "isCorrectlyClassified": true,
  "reason": "expectedDailySeasonality",
  "skipMeasurements": "previous"
}
{
  "feedback": {
    "freeTextReason": "text",
    "isCorrectlyClassified": true,
    "reason": "expectedDailySeasonality",
    "skipMeasurements": "previous",
    "submittedAt": "2026-01-01T00:00:00.000Z"
  },
  "monitorId": "text",
  "resultId": "text"
}

Delete a metric monitor

delete
/api/v1/monitors/{monitorId}

This endpoint deletes a column metric monitor or a custom SQL monitor of a V4 dataset in your organization's Soda Cloud account, knowing only the id of the monitor: the monitorId returned by POST /api/v1/monitors, or the check id from the monitor's results or from GET /api/v1/datasets/{datasetId}/metricMonitoring.

Dataset metric monitors, such as row count or freshness, cannot be deleted. Turn them off instead, with POST /api/v1/monitors/{monitorId} and configuration.isEnabled set to false.

Authorization

Only users with Manage contracts permission can delete monitors. Soda Cloud Admins can delete monitors for all datasets. See Manage dataset roles for more information.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Metric Monitors

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
monitorIdstringRequired
Responses
200

Successful response

application/json
messagestringRequired
delete/api/v1/monitors/{monitorId}
DELETE /api/v1/monitors/{monitorId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "message": "text"
}

Metric monitor result history

get
/api/v1/monitors/{monitorId}/results

This endpoint returns the history of one metric monitor's results, one row per result, newest first. Use it to see how the monitored metric evolved or since when the monitor has been flagging anomalies. GET /api/v1/monitors only carries each monitor's latest outcome.

This GET is a paginated API that uses the following parameters to request specific details:

  • monitorId: The id of the monitor, as GET /api/v1/monitors and POST /api/v1/monitors return it. A group parent monitor has no results of its own: a group-by monitor produces one result per group, on the group member rows GET /api/v1/monitors lists next to it.

  • from: Collect only the results whose dataTimestamp is on or after this moment. Supply an ISO8601 timestamp value. Defaults to 90 days before now. Example: 2026-08-01T00:00:00+01:00

  • to: Collect only the results whose dataTimestamp is on or before this moment. Supply an ISO8601 timestamp value. The window between from and to may span at most 366 days, so reading further back than that means asking for one window at a time. Example: 2026-08-31T23:59:59+01:00

  • size: Supply an integer value between 1 and 100, inclusive. The default value is 10.

  • page: Supply an integer value. The default value is 0.

Results are sorted by dataTimestamp in descending order, newest first.

Authorization

Only users with View dataset permission on the monitor's dataset can read its results. Soda Cloud Admins have access to all datasets. See Manage dataset roles for more information.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Metric Monitors

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
monitorIdstringRequired
Query parameters
fromstring · date-timeOptional
pageinteger · int32Optional
sizeinteger · int32Optional
tostring · date-timeOptional
Responses
200

Successful response

application/json
firstbooleanRequired
lastbooleanRequired
numberinteger · int32Required
sizeinteger · int32Required
totalElementsinteger · int32Required
totalPagesinteger · int32Required
get/api/v1/monitors/{monitorId}/results
GET /api/v1/monitors/{monitorId}/results HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "content": [
    {
      "dataTimestamp": "2026-01-01T00:00:00.000Z",
      "evaluationStatus": "pass",
      "id": "text",
      "incident": {
        "cloudUrl": "text",
        "id": "text",
        "name": "text",
        "number": 1,
        "status": "reported"
      },
      "monitorId": "text",
      "predictedValue": 1,
      "scanId": "text",
      "scanTime": "2026-01-01T00:00:00.000Z",
      "value": 1
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}
PreviousLicensing
NextNotification Rules

Last updated

Was this helpful?