> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/apis/rest-api/metric-monitors.md).

# Metric Monitors

Soda Cloud API Metric Monitor Endpoints

## List the monitors of a dataset

> 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]\(<https://go.soda.io/roles-dataset>) 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Metric Monitor Endpoints","name":"Metric Monitors"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"MonitorMetricTypeDTO":{"type":"string","enum":["schema","rowCount","rowsInserted","totalRowCountChange","timeliness","freshness","recordAnomalyScore","average","missingPercentage","columnFreshness","sum","distinctValuesCount","count","minimumValue","maximumValue","duplicateValuesPercentage","minimumLength","maximumLength","averageLength","standardDeviation","variance","q1","median","q3","customSql"]},"MonitorTypeDTO":{"type":"string","enum":["dataset","column","customSql"]},"PublicApiListMonitorsResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/MonitorContentDTO"}},"first":{"type":"boolean"},"last":{"type":"boolean"},"number":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32"}},"required":["content","first","last","number","size","totalElements","totalPages"]},"MonitorContentDTO":{"type":"object","properties":{"anomalousGroupMembersCount":{"type":"integer","format":"int32","description":"How many group members have a latest result that failed. Null outside the group parent monitor."},"columnName":{"type":"string","description":"Column the monitor watches. Null for a monitor that watches the whole dataset, and for a custom SQL monitor that has no column."},"evaluationStatus":{"type":"object","$ref":"#/components/schemas/EvaluationStatusDTO","description":"Outcome of the monitor's most recent result. `notEvaluated` while it has never run."},"groupByColumnValues":{"type":"array","description":"The group-by values of this group member, such as `country = BE`. Null on the group parent monitor.","items":{"type":"object","$ref":"#/components/schemas/GroupByColumnValueDTO"}},"groupByColumns":{"type":"array","description":"The columns a group-by monitor groups on. Null outside the group parent monitor.","items":{"type":"object","$ref":"#/components/schemas/GroupByColumnConfigurationDTO"}},"groupIdentity":{"type":"string","description":"Shared by the group parent monitor and its group members. Null outside group-by monitors."},"groupMembersCount":{"type":"integer","format":"int32","description":"How many group members the group-by monitor has. Null outside the group parent monitor."},"hasNotificationRules":{"type":"boolean"},"isEnabled":{"type":"boolean"},"lastDataTimestamp":{"type":"string","format":"date-time","description":"Data timestamp of the monitor's most recent result. Null while it has never run."},"metricType":{"type":"object","$ref":"#/components/schemas/MonitorMetricTypeDTO"},"monitorId":{"type":"string","description":"The id of the monitor, which the other `/api/v1/monitors` endpoints take."},"monitorName":{"type":"string"},"monitorType":{"type":"object","$ref":"#/components/schemas/MonitorTypeDTO"}},"required":["evaluationStatus","metricType","monitorId","monitorType"]},"EvaluationStatusDTO":{"type":"string","enum":["pass","warn","fail","notEvaluated","excluded"]},"GroupByColumnValueDTO":{"type":"object","properties":{"columnName":{"type":"string"},"columnValue":{"type":"object","$ref":"#/components/schemas/_object","description":"The value as the data holds it: a string, a number or a boolean."}},"required":["columnName"]},"_object":{"type":"object"},"GroupByColumnConfigurationDTO":{"type":"object","properties":{"columnName":{"type":"string"},"excludedValues":{"type":"array","items":{"type":"string"}}},"required":["columnName"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/monitors":{"get":{"description":"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`.\n\nThis GET is a paginated API that uses the following parameters to request specific details:\n\n- `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.\n\n- `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.\n\n- `metricType`: Optionally, use this parameter to collect only the monitors that watch one metric, such as `rowCount`.\n\n- `columnName`: Optionally, use this parameter to collect only the monitors that watch one column. The name must match exactly.\n\n- `size`: Supply an integer value between 1 and 200, inclusive. The default value is 50.\n\n- `page`: Supply an integer value. The default value is 0.\n\nResults are sorted with the most critical monitors first, then by the time of their most recent result, newest first.\n\nA 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`.\n\n## Authorization\n\nOnly users with **View dataset** permission can list a dataset's monitors. Soda Cloud Admins have access to all datasets. **See [Manage dataset roles](https://go.soda.io/roles-dataset) for more information.**\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Metric Monitors`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/monitors","parameters":[{"in":"query","name":"columnName","schema":{"type":"string"}},{"in":"query","name":"datasetId","required":true,"schema":{"type":"string"}},{"in":"query","name":"metricType","schema":{"type":"object","$ref":"#/components/schemas/MonitorMetricTypeDTO"}},{"in":"query","name":"monitorType","schema":{"type":"object","$ref":"#/components/schemas/MonitorTypeDTO"}},{"in":"query","name":"page","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiListMonitorsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List the monitors of a dataset","tags":["Metric Monitors"]}}}}
```

## Create a metric monitor

> 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]\(<https://go.soda.io/roles-dataset>) 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Metric Monitor Endpoints","name":"Metric Monitors"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiCreateMonitorRequestDTO":{"type":"object","properties":{"columnMetricMonitor":{"type":"object","$ref":"#/components/schemas/CreateColumnMetricMonitorDTO","description":"Send exactly one of `datasetMetricMonitor`, `columnMetricMonitor` or `customSqlMetricMonitor`."},"customSqlMetricMonitor":{"type":"object","$ref":"#/components/schemas/CreateCustomSqlMonitorDTO","description":"Send exactly one of `datasetMetricMonitor`, `columnMetricMonitor` or `customSqlMetricMonitor`."},"datasetId":{"type":"string"},"datasetMetricMonitor":{"type":"object","$ref":"#/components/schemas/DatasetMetricMonitorConfigurationDTO","description":"The dataset metric monitor to create, such as row count or freshness; a dataset has one per metric type. Send exactly one of `datasetMetricMonitor`, `columnMetricMonitor` or `customSqlMetricMonitor`."}},"required":["datasetId"]},"CreateColumnMetricMonitorDTO":{"type":"object","properties":{"columnName":{"type":"string"},"configuration":{"type":"object","$ref":"#/components/schemas/ColumnMonitorConfigurationDTO"},"metricType":{"type":"object","$ref":"#/components/schemas/ColumnMonitorMetricTypeDTO"}},"required":["columnName","configuration","metricType"]},"ColumnMonitorConfigurationDTO":{"type":"object","properties":{"groupByColumns":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/GroupByColumnConfigurationDTO"}},"exclusionZones":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ExclusionZoneDTO"}},"isEnabled":{"type":"boolean"},"isSamplingEnabled":{"type":"boolean"},"sensitivity":{"type":"number"},"thresholdStrategy":{"type":"object","$ref":"#/components/schemas/ThresholdStrategyDTO"},"validRange":{"type":"object","$ref":"#/components/schemas/ValidRangeDTO"}}},"GroupByColumnConfigurationDTO":{"type":"object","properties":{"columnName":{"type":"string"},"excludedValues":{"type":"array","items":{"type":"string"}}},"required":["columnName"]},"ExclusionZoneDTO":{"type":"object","properties":{"lowerLimit":{"type":"number"},"singleValue":{"type":"boolean"},"upperLimit":{"type":"number"}},"required":["lowerLimit","upperLimit"]},"ThresholdStrategyDTO":{"type":"object","properties":{"isLowerBoundEnabled":{"type":"boolean"},"isUpperBoundEnabled":{"type":"boolean"}},"required":["isLowerBoundEnabled","isUpperBoundEnabled"]},"ValidRangeDTO":{"type":"object","properties":{"max":{"type":"number"},"min":{"type":"number"}}},"ColumnMonitorMetricTypeDTO":{"type":"string","enum":["missingPercentage","duplicatePercentage","average","columnFreshness","sum","distinctValuesCount","count","minimumValue","maximumValue","duplicateValuesPercentage","minimumLength","maximumLength","averageLength","standardDeviation","variance","q1","median","q3"]},"CreateCustomSqlMonitorDTO":{"type":"object","properties":{"columnName":{"type":"string","description":"Optional column to associate with the monitor. If not specified, the monitor is associated with the full dataset. This is metadata only, it does not affect how the monitor operates."},"configuration":{"type":"object","$ref":"#/components/schemas/CustomSqlMonitorConfigurationDTO"},"monitorName":{"type":"string"}},"required":["configuration","monitorName"]},"CustomSqlMonitorConfigurationDTO":{"type":"object","properties":{"groupByColumnNames":{"type":"array","items":{"type":"string"}},"resultMetric":{"type":"string"},"sqlQuery":{"type":"string"},"exclusionZones":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ExclusionZoneDTO"}},"isEnabled":{"type":"boolean"},"isSamplingEnabled":{"type":"boolean"},"sensitivity":{"type":"number"},"thresholdStrategy":{"type":"object","$ref":"#/components/schemas/ThresholdStrategyDTO"},"validRange":{"type":"object","$ref":"#/components/schemas/ValidRangeDTO"}},"required":["resultMetric","sqlQuery"]},"DatasetMetricMonitorConfigurationDTO":{"type":"object","properties":{"configuration":{"type":"object","$ref":"#/components/schemas/DatasetMonitorConfigurationDTO"},"metricType":{"type":"object","$ref":"#/components/schemas/DatasetMonitorMetricTypeDTO"}},"required":["configuration","metricType"]},"DatasetMonitorConfigurationDTO":{"type":"object","properties":{"exclusionZones":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ExclusionZoneDTO"}},"isEnabled":{"type":"boolean"},"isSamplingEnabled":{"type":"boolean"},"sensitivity":{"type":"number"},"thresholdStrategy":{"type":"object","$ref":"#/components/schemas/ThresholdStrategyDTO"},"validRange":{"type":"object","$ref":"#/components/schemas/ValidRangeDTO"}}},"DatasetMonitorMetricTypeDTO":{"type":"string","enum":["rowCount","freshness","schema","rowsInserted","totalRowCountChange","timeliness","recordAnomalyScore"]},"PublicApiMonitorResponse":{"type":"object","properties":{"columnMetricMonitor":{"type":"object","$ref":"#/components/schemas/ColumnMetricMonitorDTO","description":"Set when the monitor is a column metric monitor."},"customSqlMetricMonitor":{"type":"object","$ref":"#/components/schemas/CustomMetricMonitorDTO","description":"Set when the monitor is a custom SQL monitor."},"datasetId":{"type":"string"},"datasetMetricMonitor":{"type":"object","$ref":"#/components/schemas/DatasetMetricMonitorConfigurationDTO","description":"Set when the monitor is a dataset metric monitor."},"monitorId":{"type":"string","description":"The id of the monitor. Column and custom SQL monitor objects repeat it as `checkId`."}},"required":["datasetId","monitorId"]},"ColumnMetricMonitorDTO":{"type":"object","properties":{"checkId":{"type":"string"},"columnName":{"type":"string"},"configuration":{"type":"object","$ref":"#/components/schemas/ColumnMonitorConfigurationDTO"},"metricType":{"type":"object","$ref":"#/components/schemas/ColumnMonitorMetricTypeDTO"}},"required":["checkId","columnName","configuration","metricType"]},"CustomMetricMonitorDTO":{"type":"object","properties":{"checkId":{"type":"string"},"columnName":{"type":"string"},"configuration":{"type":"object","$ref":"#/components/schemas/CustomSqlMonitorConfigurationDTO"},"monitorName":{"type":"string"}},"required":["checkId","configuration","monitorName"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/monitors":{"post":{"description":"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`.\n\nThe 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.\n\nA 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.\n\nThe response returns the new monitor with its `monitorId`, which the other `/api/v1/monitors` endpoints take.\n\n## Authorization\n\nOnly users with **Manage contracts** permission can create monitors. Soda Cloud Admins can create monitors for all datasets. **See [Manage dataset roles](https://go.soda.io/roles-dataset) for more information.**\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Metric Monitors`\n\n## Rate limiting\n\n100 requests/60 seconds","operationId":"POST/api/v1/monitors","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiCreateMonitorRequestDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiMonitorResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Create a metric monitor","tags":["Metric Monitors"]}}}}
```

## Create metric monitors in bulk

> 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]\(<https://go.soda.io/roles-dataset>) 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Metric Monitor Endpoints","name":"Metric Monitors"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiBulkCreateMonitorsRequestDTO":{"type":"object","properties":{"monitors":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/PublicApiCreateMonitorRequestDTO"}}},"required":["monitors"]},"PublicApiCreateMonitorRequestDTO":{"type":"object","properties":{"columnMetricMonitor":{"type":"object","$ref":"#/components/schemas/CreateColumnMetricMonitorDTO","description":"Send exactly one of `datasetMetricMonitor`, `columnMetricMonitor` or `customSqlMetricMonitor`."},"customSqlMetricMonitor":{"type":"object","$ref":"#/components/schemas/CreateCustomSqlMonitorDTO","description":"Send exactly one of `datasetMetricMonitor`, `columnMetricMonitor` or `customSqlMetricMonitor`."},"datasetId":{"type":"string"},"datasetMetricMonitor":{"type":"object","$ref":"#/components/schemas/DatasetMetricMonitorConfigurationDTO","description":"The dataset metric monitor to create, such as row count or freshness; a dataset has one per metric type. Send exactly one of `datasetMetricMonitor`, `columnMetricMonitor` or `customSqlMetricMonitor`."}},"required":["datasetId"]},"CreateColumnMetricMonitorDTO":{"type":"object","properties":{"columnName":{"type":"string"},"configuration":{"type":"object","$ref":"#/components/schemas/ColumnMonitorConfigurationDTO"},"metricType":{"type":"object","$ref":"#/components/schemas/ColumnMonitorMetricTypeDTO"}},"required":["columnName","configuration","metricType"]},"ColumnMonitorConfigurationDTO":{"type":"object","properties":{"groupByColumns":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/GroupByColumnConfigurationDTO"}},"exclusionZones":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ExclusionZoneDTO"}},"isEnabled":{"type":"boolean"},"isSamplingEnabled":{"type":"boolean"},"sensitivity":{"type":"number"},"thresholdStrategy":{"type":"object","$ref":"#/components/schemas/ThresholdStrategyDTO"},"validRange":{"type":"object","$ref":"#/components/schemas/ValidRangeDTO"}}},"GroupByColumnConfigurationDTO":{"type":"object","properties":{"columnName":{"type":"string"},"excludedValues":{"type":"array","items":{"type":"string"}}},"required":["columnName"]},"ExclusionZoneDTO":{"type":"object","properties":{"lowerLimit":{"type":"number"},"singleValue":{"type":"boolean"},"upperLimit":{"type":"number"}},"required":["lowerLimit","upperLimit"]},"ThresholdStrategyDTO":{"type":"object","properties":{"isLowerBoundEnabled":{"type":"boolean"},"isUpperBoundEnabled":{"type":"boolean"}},"required":["isLowerBoundEnabled","isUpperBoundEnabled"]},"ValidRangeDTO":{"type":"object","properties":{"max":{"type":"number"},"min":{"type":"number"}}},"ColumnMonitorMetricTypeDTO":{"type":"string","enum":["missingPercentage","duplicatePercentage","average","columnFreshness","sum","distinctValuesCount","count","minimumValue","maximumValue","duplicateValuesPercentage","minimumLength","maximumLength","averageLength","standardDeviation","variance","q1","median","q3"]},"CreateCustomSqlMonitorDTO":{"type":"object","properties":{"columnName":{"type":"string","description":"Optional column to associate with the monitor. If not specified, the monitor is associated with the full dataset. This is metadata only, it does not affect how the monitor operates."},"configuration":{"type":"object","$ref":"#/components/schemas/CustomSqlMonitorConfigurationDTO"},"monitorName":{"type":"string"}},"required":["configuration","monitorName"]},"CustomSqlMonitorConfigurationDTO":{"type":"object","properties":{"groupByColumnNames":{"type":"array","items":{"type":"string"}},"resultMetric":{"type":"string"},"sqlQuery":{"type":"string"},"exclusionZones":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ExclusionZoneDTO"}},"isEnabled":{"type":"boolean"},"isSamplingEnabled":{"type":"boolean"},"sensitivity":{"type":"number"},"thresholdStrategy":{"type":"object","$ref":"#/components/schemas/ThresholdStrategyDTO"},"validRange":{"type":"object","$ref":"#/components/schemas/ValidRangeDTO"}},"required":["resultMetric","sqlQuery"]},"DatasetMetricMonitorConfigurationDTO":{"type":"object","properties":{"configuration":{"type":"object","$ref":"#/components/schemas/DatasetMonitorConfigurationDTO"},"metricType":{"type":"object","$ref":"#/components/schemas/DatasetMonitorMetricTypeDTO"}},"required":["configuration","metricType"]},"DatasetMonitorConfigurationDTO":{"type":"object","properties":{"exclusionZones":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ExclusionZoneDTO"}},"isEnabled":{"type":"boolean"},"isSamplingEnabled":{"type":"boolean"},"sensitivity":{"type":"number"},"thresholdStrategy":{"type":"object","$ref":"#/components/schemas/ThresholdStrategyDTO"},"validRange":{"type":"object","$ref":"#/components/schemas/ValidRangeDTO"}}},"DatasetMonitorMetricTypeDTO":{"type":"string","enum":["rowCount","freshness","schema","rowsInserted","totalRowCountChange","timeliness","recordAnomalyScore"]},"PublicApiBulkCreateMonitorsResponse":{"type":"object","properties":{"createdMonitors":{"type":"array","description":"The monitors that were created, in the order of the request.","items":{"type":"object","$ref":"#/components/schemas/PublicApiMonitorResponse"}},"failedMonitors":{"type":"array","description":"The entries that could not be created, with their position in `monitors`.","items":{"type":"object","$ref":"#/components/schemas/FailedMonitorCreationDTO"}}},"required":["createdMonitors","failedMonitors"]},"PublicApiMonitorResponse":{"type":"object","properties":{"columnMetricMonitor":{"type":"object","$ref":"#/components/schemas/ColumnMetricMonitorDTO","description":"Set when the monitor is a column metric monitor."},"customSqlMetricMonitor":{"type":"object","$ref":"#/components/schemas/CustomMetricMonitorDTO","description":"Set when the monitor is a custom SQL monitor."},"datasetId":{"type":"string"},"datasetMetricMonitor":{"type":"object","$ref":"#/components/schemas/DatasetMetricMonitorConfigurationDTO","description":"Set when the monitor is a dataset metric monitor."},"monitorId":{"type":"string","description":"The id of the monitor. Column and custom SQL monitor objects repeat it as `checkId`."}},"required":["datasetId","monitorId"]},"ColumnMetricMonitorDTO":{"type":"object","properties":{"checkId":{"type":"string"},"columnName":{"type":"string"},"configuration":{"type":"object","$ref":"#/components/schemas/ColumnMonitorConfigurationDTO"},"metricType":{"type":"object","$ref":"#/components/schemas/ColumnMonitorMetricTypeDTO"}},"required":["checkId","columnName","configuration","metricType"]},"CustomMetricMonitorDTO":{"type":"object","properties":{"checkId":{"type":"string"},"columnName":{"type":"string"},"configuration":{"type":"object","$ref":"#/components/schemas/CustomSqlMonitorConfigurationDTO"},"monitorName":{"type":"string"}},"required":["checkId","configuration","monitorName"]},"FailedMonitorCreationDTO":{"type":"object","properties":{"datasetId":{"type":"string"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"index":{"type":"integer","format":"int32","description":"Position of the entry in `monitors`, starting at 0."}},"required":["datasetId","errorCode","errorMessage","index"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/monitors/actions/bulkCreate":{"post":{"description":"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`.\n\nEntries 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`.\n\n## Authorization\n\nOnly 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](https://go.soda.io/roles-dataset) for more information.**\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Metric Monitors`\n\n## Rate limiting\n\n10 requests/60 seconds","operationId":"POST/api/v1/monitors/actions/bulkCreate","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiBulkCreateMonitorsRequestDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiBulkCreateMonitorsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Create metric monitors in bulk","tags":["Metric Monitors"]}}}}
```

## Submit the same feedback on several monitor results

> 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]\(<https://go.soda.io/roles-dataset>) 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Metric Monitor Endpoints","name":"Metric Monitors"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"BulkSubmitMonitorResultFeedbackDTO":{"type":"object","properties":{"feedback":{"type":"object","$ref":"#/components/schemas/SubmitMonitorResultFeedbackDTO"},"resultIds":{"type":"array","description":"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.","items":{"type":"string"}}},"required":["feedback","resultIds"]},"SubmitMonitorResultFeedbackDTO":{"type":"object","properties":{"isCorrectlyClassified":{"type":"boolean","description":"Whether the anomaly detection model classified this result correctly."}},"required":["isCorrectlyClassified"]},"PublicApiBulkSubmitMonitorResultFeedbackResponse":{"type":"object","properties":{"feedback":{"type":"object","$ref":"#/components/schemas/MonitorResultFeedbackDTO","description":"The feedback as it is now stored on every one of them, including `submittedAt`, when Soda Cloud stored it."},"resultIds":{"type":"array","description":"The monitor results that now carry the feedback, each once, in the order they were requested.","items":{"type":"string"}}},"required":["feedback","resultIds"]},"MonitorResultFeedbackDTO":{"type":"object","properties":{"isCorrectlyClassified":{"type":"boolean","description":"Whether the anomaly detection model classified this result correctly. Null on feedback that did not judge the classification."},"submittedAt":{"type":"string","format":"date-time","description":"When Soda Cloud stored the feedback."}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/monitors/results/actions/feedback":{"post":{"description":"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.\n\nIt 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.\n\nSubmitting feedback replaces the feedback the results already carried. Both result listings return it again under `feedback`, after a short delay.\n\nThe body takes the following fields:\n\n- `resultIds`: The monitor results that all get the same feedback. At least one, at most 100.\n\n- `feedback`: The same body as **Submit feedback on a monitor result**.\n\n## Authorization\n\nOnly 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](https://go.soda.io/roles-dataset) for more information.**\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Metric Monitors`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"POST/api/v1/monitors/results/actions/feedback","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/BulkSubmitMonitorResultFeedbackDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiBulkSubmitMonitorResultFeedbackResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Submit the same feedback on several monitor results","tags":["Metric Monitors"]}}}}
```

## Submit feedback on a monitor result

> This endpoint tells the anomaly detection model behind a metric monitor whether it classified a result correctly. 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 one field:\
> \
> \- \`isCorrectlyClassified\`: Whether the model classified this result correctly. Required.\
> \
> \## 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]\(<https://go.soda.io/roles-dataset>) 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Metric Monitor Endpoints","name":"Metric Monitors"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"SubmitMonitorResultFeedbackDTO":{"type":"object","properties":{"isCorrectlyClassified":{"type":"boolean","description":"Whether the anomaly detection model classified this result correctly."}},"required":["isCorrectlyClassified"]},"PublicApiSubmitMonitorResultFeedbackResponse":{"type":"object","properties":{"feedback":{"type":"object","$ref":"#/components/schemas/MonitorResultFeedbackDTO","description":"The feedback as it is now stored, including `submittedAt`, when Soda Cloud stored it."},"monitorId":{"type":"string","description":"The monitor the result belongs to. Use it in `GET /api/v1/checks/{checkId}/results`."},"resultId":{"type":"string"}},"required":["feedback","monitorId","resultId"]},"MonitorResultFeedbackDTO":{"type":"object","properties":{"isCorrectlyClassified":{"type":"boolean","description":"Whether the anomaly detection model classified this result correctly. Null on feedback that did not judge the classification."},"submittedAt":{"type":"string","format":"date-time","description":"When Soda Cloud stored the feedback."}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/monitors/results/{resultId}/feedback":{"post":{"description":"This endpoint tells the anomaly detection model behind a metric monitor whether it classified a result correctly. 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`.\n\nSubmitting feedback replaces the feedback the result already carried. Both result listings return it again under `feedback`, after a short delay.\n\nThe body takes one field:\n\n- `isCorrectlyClassified`: Whether the model classified this result correctly. Required.\n\n## Authorization\n\nOnly 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](https://go.soda.io/roles-dataset) for more information.**\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Metric Monitors`\n\n## Rate limiting\n\n100 requests/60 seconds","operationId":"POST/api/v1/monitors/results/{resultId}/feedback","parameters":[{"in":"path","name":"resultId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/SubmitMonitorResultFeedbackDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiSubmitMonitorResultFeedbackResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Submit feedback on a monitor result","tags":["Metric Monitors"]}}}}
```

## Delete a metric monitor

> 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]\(<https://go.soda.io/roles-dataset>) 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Metric Monitor Endpoints","name":"Metric Monitors"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiDeleteMonitorResponse":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/monitors/{monitorId}":{"delete":{"description":"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`.\n\nDataset 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`.\n\n## Authorization\n\nOnly users with **Manage contracts** permission can delete monitors. Soda Cloud Admins can delete monitors for all datasets. **See [Manage dataset roles](https://go.soda.io/roles-dataset) for more information.**\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Metric Monitors`\n\n## Rate limiting\n\n100 requests/60 seconds","operationId":"DELETE/api/v1/monitors/{monitorId}","parameters":[{"in":"path","name":"monitorId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiDeleteMonitorResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Delete a metric monitor","tags":["Metric Monitors"]}}}}
```

## Metric monitor result history

> 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.\
> \
> \## Record anomaly detection\
> \
> A record anomaly detection monitor compares the rows of one time partition with the rows of past partitions. Its \`value\` is an anomaly score from 0 to 1, judged against \`expectedRange\` like any other metric. \`diagnostics.recordAnomalyDetection\` says which partition was checked, which past partition it looked most like, and which columns shifted.\
> \
> In the explanation, the bucket bounds of a \`temporal\` column are in seconds, and \`axis.semantic\` says what they count from. With \`secondsFromPartitionStart\`, both partitions are measured from their own start, so one bucket covers the same stretch of each partition.\
> \
> \## 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]\(<https://go.soda.io/roles-dataset>) 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Metric Monitor Endpoints","name":"Metric Monitors"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiMonitorResultsResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/MonitorResultContentDTO"}},"first":{"type":"boolean"},"last":{"type":"boolean"},"number":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32"}},"required":["content","first","last","number","size","totalElements","totalPages"]},"MonitorResultContentDTO":{"type":"object","properties":{"dataTimestamp":{"type":"string","format":"date-time","description":"The moment in the data the result is about, which `from` and `to` filter on."},"diagnostics":{"type":"object","$ref":"#/components/schemas/MonitorResultDiagnosticsDTO","description":"What one type of monitor adds to its result, with one key per type. Only the key of this monitor's type is set. Null when the monitor's type adds nothing."},"evaluationStatus":{"type":"object","$ref":"#/components/schemas/EvaluationStatusDTO"},"expectedRange":{"type":"object","$ref":"#/components/schemas/MonitorExpectedRangeDTO","description":"The range the value had to fall in to pass, bounds included. A null bound means the value could not fail on that side. Null when the monitor did not evaluate the value, or could not fail on either side."},"feedback":{"type":"object","$ref":"#/components/schemas/MonitorResultFeedbackDTO"},"id":{"type":"string"},"incident":{"type":"object","$ref":"#/components/schemas/IncidentSlimDTO"},"monitorId":{"type":"string"},"predictedValue":{"type":"number"},"scanId":{"type":"string"},"scanTime":{"type":"string","format":"date-time","description":"When the scan that produced the result ran."},"value":{"type":"number","description":"The measured metric. For record anomaly detection, the anomaly score from 0 to 1."}},"required":["dataTimestamp","evaluationStatus","id","monitorId"]},"MonitorResultDiagnosticsDTO":{"type":"object","properties":{"recordAnomalyDetection":{"type":"object","$ref":"#/components/schemas/RecordAnomalyDetectionDiagnosticsDTO"}}},"RecordAnomalyDetectionDiagnosticsDTO":{"type":"object","properties":{"explanation":{"type":"object","$ref":"#/components/schemas/RadExplanationDTO","description":"Why the partition looked unusual. Null when the run produced no explanation."},"monitoredColumns":{"type":"array","description":"The columns this run compared. Empty when it compared none, as on a run without a score.","items":{"type":"string"}},"partition":{"type":"object","$ref":"#/components/schemas/RadPartitionDTO"},"reference":{"type":"object","$ref":"#/components/schemas/RadReferencePartitionDTO","description":"The past partition that looked most like this one. The explanation compares against it. Null when no past partition was selected, as on a `skipped` run."},"runPhase":{"type":"object","$ref":"#/components/schemas/RadRunPhaseDTO","description":"`skipped`: the run produced no score, for example because the partition was empty, had too few rows, or had too few past partitions to compare with. `warmingUp`: fewer past partitions are available than the full window, so a score is less settled. `steady`: the full window of past partitions is available."}},"required":["monitoredColumns","partition","runPhase"]},"RadExplanationDTO":{"type":"object","properties":{"columnEffects":{"type":"array","description":"Columns whose values shifted across the whole partition. Empty when no column stood out.","items":{"type":"object","$ref":"#/components/schemas/RadColumnEffectDTO"}},"segmentEffects":{"type":"array","description":"Columns whose values shifted more within a slice of rows than across the whole partition. Empty when no slice stood out.","items":{"type":"object","$ref":"#/components/schemas/RadSegmentEffectDTO"}}},"required":["columnEffects","segmentEffects"]},"RadColumnEffectDTO":{"type":"object","properties":{"column":{"type":"string"},"distribution":{"type":"object","$ref":"#/components/schemas/RadValueDistributionDTO"},"kind":{"type":"object","$ref":"#/components/schemas/RadFeatureKindDTO"}},"required":["column","distribution","kind"]},"RadValueDistributionDTO":{"type":"object","properties":{"axis":{"type":"object","$ref":"#/components/schemas/RadAxisDTO","description":"How to read the `min` and `max` bucket bounds of a `temporal` column, which are in seconds. Null for the other kinds."},"buckets":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/RadBucketDTO"}},"missing":{"type":"object","$ref":"#/components/schemas/RadBucketCountsDTO","description":"Rows where the column has no value. Null when there are none."},"other":{"type":"object","$ref":"#/components/schemas/RadOtherCategoriesDTO","description":"Rows in the categories that are not listed in `buckets`. Only set for a `categorical` column with more categories than are listed."}},"required":["buckets"]},"RadAxisDTO":{"type":"object","properties":{"resolution":{"type":"object","$ref":"#/components/schemas/RadAxisResolutionDTO","description":"The finest unit seen in the source column's values. `day` means a date column. Null for a duration."},"semantic":{"type":"object","$ref":"#/components/schemas/RadAxisSemanticDTO"},"timezone":{"type":"string","description":"The timezone of the source column. Null for a duration."}},"required":["semantic"]},"RadAxisResolutionDTO":{"type":"string","enum":["day","hour","minute","second","millisecond","microsecond","nanosecond"]},"RadAxisSemanticDTO":{"type":"string","enum":["secondsFromPartitionStart","unixSeconds","secondsDuration"]},"RadBucketDTO":{"type":"object","properties":{"category":{"type":"string","description":"The category this bucket counts. Only set for a `categorical` column."},"max":{"type":"number","description":"The upper bound of this bucket, inclusive. Null for a `categorical` column."},"min":{"type":"number","description":"The lower bound of this bucket, exclusive except on the first bucket. Null for a `categorical` column."},"presentCount":{"type":"integer","format":"int32","description":"Rows in this bucket, counted in a sample of the checked partition."},"presentProportion":{"type":"number","description":"This bucket's share of the checked partition's sample, from 0 to 1."},"referenceCount":{"type":"integer","format":"int32","description":"Rows in this bucket, counted in a sample of the reference partition."},"referenceProportion":{"type":"number","description":"This bucket's share of the reference partition's sample, from 0 to 1."}},"required":["presentCount","presentProportion","referenceCount","referenceProportion"]},"RadBucketCountsDTO":{"type":"object","properties":{"presentCount":{"type":"integer","format":"int32","description":"Rows in this bucket, counted in a sample of the checked partition."},"presentProportion":{"type":"number","description":"This bucket's share of the checked partition's sample, from 0 to 1."},"referenceCount":{"type":"integer","format":"int32","description":"Rows in this bucket, counted in a sample of the reference partition."},"referenceProportion":{"type":"number","description":"This bucket's share of the reference partition's sample, from 0 to 1."}},"required":["presentCount","presentProportion","referenceCount","referenceProportion"]},"RadOtherCategoriesDTO":{"type":"object","properties":{"categoryCount":{"type":"integer","format":"int32","description":"How many categories this bucket folds together."},"presentCount":{"type":"integer","format":"int32","description":"Rows in this bucket, counted in a sample of the checked partition."},"presentProportion":{"type":"number","description":"This bucket's share of the checked partition's sample, from 0 to 1."},"referenceCount":{"type":"integer","format":"int32","description":"Rows in this bucket, counted in a sample of the reference partition."},"referenceProportion":{"type":"number","description":"This bucket's share of the reference partition's sample, from 0 to 1."}},"required":["categoryCount","presentCount","presentProportion","referenceCount","referenceProportion"]},"RadFeatureKindDTO":{"type":"string","enum":["categorical","numeric","temporal"]},"RadSegmentEffectDTO":{"type":"object","properties":{"column":{"type":"string","description":"The column whose values shifted within the segment."},"distribution":{"type":"object","$ref":"#/components/schemas/RadValueDistributionDTO"},"kind":{"type":"object","$ref":"#/components/schemas/RadFeatureKindDTO"},"rowCounts":{"type":"object","$ref":"#/components/schemas/RadRowCountsDTO"},"segment":{"type":"object","$ref":"#/components/schemas/RadSegmentDTO"}},"required":["column","distribution","kind","rowCounts","segment"]},"RadRowCountsDTO":{"type":"object","properties":{"present":{"type":"integer","format":"int32","description":"Rows in the segment, counted in a sample of the checked partition."},"reference":{"type":"integer","format":"int32","description":"Rows in the segment, counted in a sample of the reference partition."}},"required":["present","reference"]},"RadSegmentDTO":{"type":"object","properties":{"axis":{"type":"object","$ref":"#/components/schemas/RadAxisDTO","description":"How to read the range bounds when the column is a timestamp. Null otherwise."},"column":{"type":"string"},"operator":{"type":"object","$ref":"#/components/schemas/RadSegmentOperatorDTO"},"range":{"type":"object","$ref":"#/components/schemas/RadSegmentRangeDTO","description":"The bounds the column falls within. Only set for `range`."},"values":{"type":"array","description":"The categories the column takes: one for `eq`, several for `in`. Null for the other operators.","items":{"type":"string"}}},"required":["column","operator"]},"RadSegmentOperatorDTO":{"type":"string","enum":["eq","in","range","isMissing"]},"RadSegmentRangeDTO":{"type":"object","properties":{"closed":{"type":"object","$ref":"#/components/schemas/RadRangeClosedDTO","description":"Which of the bounds belong to the range."},"max":{"type":"number"},"min":{"type":"number"}},"required":["closed"]},"RadRangeClosedDTO":{"type":"string","enum":["left","right","both","neither"]},"RadPartitionDTO":{"type":"object","properties":{"end":{"type":"string","format":"date-time","description":"The end of the partition, exclusive."},"rowCount":{"type":"integer","format":"int32","description":"Rows in the whole partition, not in the sample the bucket counts are taken from. 0 means the partition was empty."},"start":{"type":"string","format":"date-time"}},"required":["end","start"]},"RadReferencePartitionDTO":{"type":"object","properties":{"end":{"type":"string","format":"date-time","description":"The end of the partition, exclusive."},"start":{"type":"string","format":"date-time"}},"required":["end","start"]},"RadRunPhaseDTO":{"type":"string","enum":["skipped","warmingUp","steady"]},"EvaluationStatusDTO":{"type":"string","enum":["pass","warn","fail","notEvaluated","excluded"]},"MonitorExpectedRangeDTO":{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}}},"MonitorResultFeedbackDTO":{"type":"object","properties":{"isCorrectlyClassified":{"type":"boolean","description":"Whether the anomaly detection model classified this result correctly. Null on feedback that did not judge the classification."},"submittedAt":{"type":"string","format":"date-time","description":"When Soda Cloud stored the feedback."}}},"IncidentSlimDTO":{"type":"object","properties":{"cloudUrl":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"number":{"type":"integer","format":"int32"},"status":{"type":"object","$ref":"#/components/schemas/IncidentStatusDTO"}},"required":["cloudUrl","id","name","number","status"]},"IncidentStatusDTO":{"type":"string","enum":["reported","investigating","fixing","resolved"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/monitors/{monitorId}/results":{"get":{"description":"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.\n\nThis GET is a paginated API that uses the following parameters to request specific details:\n\n- `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.\n\n- `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`\n\n- `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`\n\n- `size`: Supply an integer value between 1 and 100, inclusive. The default value is 10.\n\n- `page`: Supply an integer value. The default value is 0.\n\nResults are sorted by `dataTimestamp` in descending order, newest first.\n\n## Record anomaly detection\n\nA record anomaly detection monitor compares the rows of one time partition with the rows of past partitions. Its `value` is an anomaly score from 0 to 1, judged against `expectedRange` like any other metric. `diagnostics.recordAnomalyDetection` says which partition was checked, which past partition it looked most like, and which columns shifted.\n\nIn the explanation, the bucket bounds of a `temporal` column are in seconds, and `axis.semantic` says what they count from. With `secondsFromPartitionStart`, both partitions are measured from their own start, so one bucket covers the same stretch of each partition.\n\n## Authorization\n\nOnly 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](https://go.soda.io/roles-dataset) for more information.**\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Metric Monitors`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/monitors/{monitorId}/results","parameters":[{"in":"path","name":"monitorId","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"page","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"to","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiMonitorResultsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Metric monitor result history","tags":["Metric Monitors"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.soda.io/apis/rest-api/metric-monitors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.