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.

Checks

Soda Cloud API Check Endpoints

Check information

get
/api/v1/checks

This endpoint enables you to gather information about the checks that in exist in your organization's Soda Cloud account, including information about the datasets and agreements with which they are associated and the incidents to which they are linked. .

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

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

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

  • datasetId: Optionally, use this parameter to collect only the information for checks associated with a specific dataset. Find the datasetId in the URL of the dataset page in Soda Cloud.

  • dataStandardId: Optionally, use this parameter to collect only the information for checks belonging to a specific data standard. Find the dataStandardId in the URL of the data standard page in Soda Cloud.

  • scanId: Optionally, use this parameter to collect only the information for checks that produced a result in a specific scan run. Find the scanId in the URL of the scan page in Soda Cloud, or use the value of X-Soda-Scan-Id returned when you triggered the scan.

  • source: Optionally, use this parameter to collect only the information for checks that were defined in one place: soda-contract for the checks of a data contract, data-standard for the checks a data standard added, soda-metric-monitoring for metric monitors, soda-cloud for no-code checks written in Soda Cloud, soda-library or soda-core for the checks of a SodaCL scan, dbt for ingested dbt tests, and soda-sql for the checks of a legacy Soda SQL scan.

  • checkIds: Optionally, use this parameter to collect only the information for a specific batch of checks. Provide multiple values as a comma-separated list of check IDs, which you can find on the individual check pages in Soda Cloud. This query parameter is limited to 1000 check IDs. You can supply other query parameters with checkIds, but they do not filter or paginate the batch results.

  • datasourceId: Optionally, use this parameter to collect only the information for checks on the datasets of a specific datasource. Find the datasourceId in the URL of the datasource page in Soda Cloud.

  • name: Optionally, use this parameter to collect only the information for checks with exactly this name.

  • column: Optionally, use this parameter to collect only the information for checks on exactly this column.

  • group: Optionally, use this parameter to collect only the information for checks in the check group with exactly this name, as returned in group.name.

  • evaluationStatus: Optionally, use this parameter to collect only the information for checks with a specific evaluation status. One of pass, warn, fail, notEvaluated, excluded.

  • checkType: Optionally, use this parameter to collect only the information for checks of a specific type, for example missing or freshness, as returned in checkType.

  • metricType: Optionally, use this parameter to collect only the information for checks on a specific metric, for example rowCount, as returned in metricType. An unknown metric type is rejected with a 400 error.

  • attribute: Optionally, use this parameter to collect only the information for checks carrying a check attribute, written as a single key:value pair, for example team:Engineering. The key is the attribute's name, and it always matches exactly. For an attribute that allows several values, the check matches when any one of its selected values is the one you asked for. A value that is missing or a key that is not made up of letters, digits and underscores is rejected with a 400 error.

  • from: Optionally, use this parameter to collect only the checks created on or after this moment, compared against each check's createdAt timestamp. Supply an ISO8601 timestamp value. Example: 2026-08-01T00:00:00+01:00

  • to: Optionally, use this parameter to collect only the checks created on or before this moment, compared against each check's createdAt timestamp. Supply an ISO8601 timestamp value. Example: 2026-08-01T23:59:59+01:00

  • caseInsensitive: Optionally, set this to true to ignore letter case in every text match of this request: name, column, group and the value of attribute. The default is false, so those parameters match case-sensitively.

  • sort: Optionally, sort the results by name (default) or createdAt.

  • order: Optionally, sort in asc (default) or desc order.

Without checkIds, the other filters can be combined and are applied together (AND). When checkIds is supplied, Soda Cloud returns the named checks you are allowed to view without applying other filters or pagination. Malformed or out-of-range parameter values may still be rejected during request parsing or validation.

If not specified, the query gathers information for all checks in the account and sorts the results by check name in ascending order.

This list also includes metric monitors, as checks whose source is soda-metric-monitoring. Listing monitors here is deprecated. Use GET /api/v1/monitors to list monitors, and GET /api/v1/monitors/{monitorId}/results to read their results; both support V4 datasets only. For the same reason, anomalyDetectionDetails in lastCheckResultValue is deprecated. Only a monitor's result fills that field.

Authorization

Soda only returns the checks linked to datasets to which the user has View dataset permissions. Soda Cloud Admins have access to all checks.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

Checks

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Query parameters
attributestringOptional
caseInsensitivebooleanOptional
checkIdsstringOptional
checkTypeobject · enumOptionalPossible values:
columnstringOptional
dataStandardIdstringOptional
datasetIdstringOptional
datasourceIdstringOptional
evaluationStatusobject · enumOptionalPossible values:
fromstring · date-timeOptional
groupstringOptional
metricTypestringOptional
namestringOptional
orderobject · enumOptionalPossible values:
pageinteger · int32Optional
scanIdstringOptional
sizeinteger · int32Optional
sortobject · enumOptionalPossible values:
sourceobject · enumOptionalPossible values:
tostring · date-timeOptional
Responses
200

Successful response

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

{
  "content": [
    {
      "attributes": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "checkType": "text",
      "cloudUrl": "text",
      "column": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "datasets": [
        {
          "cloudUrl": "text",
          "id": "text",
          "name": "text",
          "qualifiedName": "text"
        }
      ],
      "definition": "text",
      "description": "text",
      "evaluationStatus": "pass",
      "group": {
        "groupType": "text",
        "identity": "text",
        "name": "text"
      },
      "id": "text",
      "incidents": [
        {
          "cloudUrl": "text",
          "id": "text",
          "name": "text",
          "number": 1,
          "status": "reported"
        }
      ],
      "lastCheckResultValue": {
        "dataTimestamp": "2026-01-01T00:00:00.000Z",
        "diagnostics": {
          "aggregate": {
            "checkRowsTested": 1,
            "datasetRowsTested": 1
          },
          "aggregate_diff": {
            "diff": 1,
            "diffPercent": 1,
            "function": "text",
            "sourceCheckRowsTested": 1,
            "sourceDatasetRowsTested": 1,
            "sourceValue": 1,
            "targetCheckRowsTested": 1,
            "targetDatasetRowsTested": 1,
            "targetValue": 1
          },
          "duplicate": {
            "checkRowsTested": 1,
            "datasetRowsTested": 1,
            "failedRowsCount": 1,
            "failedRowsDataQuery": "text",
            "failedRowsKeysQuery": "text",
            "failedRowsPercent": 1,
            "failedRowsSourceQuery": "text",
            "missingCount": 1
          },
          "duplicate_diff": {
            "duplicateCountDiff": 1,
            "duplicateDiffPercent": 1,
            "sourceCheckRowsTested": 1,
            "sourceDatasetRowsTested": 1,
            "sourceDuplicateCount": 1,
            "targetCheckRowsTested": 1,
            "targetDatasetRowsTested": 1,
            "targetDuplicateCount": 1
          },
          "failed_rows": {
            "checkRowsTested": 1,
            "datasetRowsTested": 1,
            "failedRowsCount": 1,
            "failedRowsDataQuery": "text",
            "failedRowsKeysQuery": "text",
            "failedRowsPercent": 1,
            "failedRowsSourceQuery": "text"
          },
          "freshness": {
            "actualTimestamp": "2026-01-01T00:00:00.000Z",
            "actualTimestampUtc": "2026-01-01T00:00:00.000Z",
            "datasetRowsTested": 1,
            "expectedTimestamp": "2026-01-01T00:00:00.000Z",
            "expectedTimestampUtc": "2026-01-01T00:00:00.000Z"
          },
          "freshness_diff": {
            "freshnessDiff": 1,
            "freshnessDiffUnit": "minutes",
            "sourceCheckRowsTested": 1,
            "sourceDatasetRowsTested": 1,
            "sourceMaxTimestamp": "2026-01-01T00:00:00.000Z",
            "sourceMaxTimestampUtc": "2026-01-01T00:00:00.000Z",
            "targetCheckRowsTested": 1,
            "targetDatasetRowsTested": 1,
            "targetMaxTimestamp": "2026-01-01T00:00:00.000Z",
            "targetMaxTimestampUtc": "2026-01-01T00:00:00.000Z"
          },
          "fuzzy_duplicate": {
            "candidateRowsScored": 1,
            "checkRowsTested": 1,
            "clusterCount": 1,
            "datasetRowsTested": 1,
            "failedRowsCount": 1,
            "failedRowsDataQuery": "text",
            "failedRowsKeysQuery": "text",
            "failedRowsSourceQuery": "text",
            "fuzzyDuplicateCount": 1,
            "fuzzyDuplicatePercent": 1,
            "meanConfidence": 1
          },
          "group_by": {
            "diagnosticsCount": 1,
            "failedRowsDataQuery": "text",
            "failedRowsKeysQuery": "text",
            "failedRowsSourceQuery": "text",
            "groups": [
              {
                "group": "text",
                "rowsTested": 1,
                "status": "pass",
                "value": 1
              }
            ]
          },
          "hierarchy": {
            "brokenPathCount": 1,
            "checkRowsTested": 1,
            "datasetRowsTested": 1,
            "failedRowsCount": 1,
            "failedRowsDataQuery": "text",
            "failedRowsKeysQuery": "text",
            "failedRowsSourceQuery": "text",
            "invalidValueCount": 1,
            "missingValueCount": 1
          },
          "invalid": {
            "checkRowsTested": 1,
            "datasetRowsTested": 1,
            "failedRowsCount": 1,
            "failedRowsDataQuery": "text",
            "failedRowsKeysQuery": "text",
            "failedRowsPercent": 1,
            "failedRowsSourceQuery": "text",
            "missingCount": 1
          },
          "llm": {
            "completionTokens": 1,
            "failedRowsCount": 1,
            "failedRowsDataQuery": "text",
            "failedRowsKeysQuery": "text",
            "failedRowsSourceQuery": "text",
            "model": "text",
            "promptTokens": 1,
            "rowsChecked": 1,
            "rowsFailed": 1,
            "rowsFailedPercent": 1,
            "tokensSpent": 1
          },
          "metric": {
            "datasetRowsTested": 1
          },
          "metric_diff": {
            "metricDiff": 1,
            "metricDiffPercent": 1,
            "sourceCheckRowsTested": 1,
            "sourceDatasetRowsTested": 1,
            "sourceMetric": 1,
            "targetCheckRowsTested": 1,
            "targetDatasetRowsTested": 1,
            "targetMetric": 1
          },
          "missing": {
            "checkRowsTested": 1,
            "datasetRowsTested": 1,
            "failedRowsCount": 1,
            "failedRowsDataQuery": "text",
            "failedRowsKeysQuery": "text",
            "failedRowsPercent": 1,
            "failedRowsSourceQuery": "text"
          },
          "reference_diff": {
            "diffCount": 1,
            "diffPercent": 1,
            "exclusiveInSource": 1,
            "exclusiveInTarget": 1,
            "sourceCheckRowsTested": 1,
            "sourceDatasetRowsTested": 1,
            "targetCheckRowsTested": 1,
            "targetDatasetRowsTested": 1
          },
          "row_count": {
            "checkRowsTested": 1,
            "datasetRowsTested": 1
          },
          "row_count_diff": {
            "rowCountDiff": 1,
            "rowCountDiffPercent": 1,
            "sourceCheckRowsTested": 1,
            "sourceDatasetRowsTested": 1,
            "targetCheckRowsTested": 1,
            "targetDatasetRowsTested": 1
          },
          "rows_diff": {
            "changed": 1,
            "diffCount": 1,
            "diffPercent": 1,
            "exclusiveInSource": 1,
            "exclusiveInTarget": 1,
            "nullKeyRowsSource": 1,
            "nullKeyRowsTarget": 1,
            "sourceCheckRowsTested": 1,
            "sourceDatasetRowsTested": 1,
            "targetCheckRowsTested": 1,
            "targetDatasetRowsTested": 1
          },
          "schema": {
            "actual": [
              {
                "name": "text",
                "type": "text"
              }
            ],
            "expected": [
              {
                "name": "text",
                "type": "text"
              }
            ]
          },
          "schema_diff": {
            "missingInSource": [
              {
                "name": "text",
                "type": "text"
              }
            ],
            "missingInTarget": [
              {
                "name": "text",
                "type": "text"
              }
            ],
            "typeMismatch": [
              {
                "sourceColumn": "text",
                "sourceType": "text",
                "targetColumn": "text",
                "targetType": "text"
              }
            ]
          }
        },
        "id": "text",
        "measure": "time",
        "value": 1,
        "valueLabel": "text",
        "valueSeries": {
          "values": [
            {
              "label": "text",
              "level": "pass",
              "value": 1
            }
          ]
        }
      },
      "metricType": "text",
      "name": "text",
      "source": "soda-sql"
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}

Delete a check

delete
/api/v1/checks/{checkId}

This endpoint allows you to delete a specific check in your organization's Soda Cloud account.

Authorization

Only users with Manage checks permission (V3 datasets) or Manage contracts permission (V4 datasets) can delete checks. Soda Cloud Admins can delete checks 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

Checks

Rate limiting

1000 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
checkIdstringRequired
Responses
400

Bad request

application/json
codestringOptional
messagestringOptional
delete/api/v1/checks/{checkId}
DELETE /api/v1/checks/{checkId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "code": "text",
  "message": "text"
}

Check result history

get
/api/v1/checks/{checkId}/results

This endpoint returns the history of one check's results, one row per result, newest first. Use it to see how the check evolved or since when it has been failing. GET /api/v1/checks only carries the check's latest result.

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

  • checkId: The ID of the check, which you can find on the check page in Soda Cloud. A metric monitor's id is still accepted here, but that is deprecated: read a monitor's results with GET /api/v1/monitors/{monitorId}/results, which supports V4 datasets only. anomalyDetectionDetails is deprecated here for the same reason; a SodaCL anomaly detection check, which is not a monitor, keeps filling it on this route.

  • from: Collect only the results whose dataTimestamp is on or after this moment. Supply an ISO8601 timestamp value. Defaults to 30 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 30 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 1000, inclusive. The default value is 100.

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

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

Authorization

The check must be linked to a dataset to which the user has View dataset permissions; otherwise the check is reported as not found. Soda Cloud Admins have access to all checks. 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

Checks

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
checkIdstringRequired
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/checks/{checkId}/results
GET /api/v1/checks/{checkId}/results HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "content": [
    {
      "checkId": "text",
      "dataTimestamp": "2026-01-01T00:00:00.000Z",
      "diagnostics": {
        "aggregate": {
          "checkRowsTested": 1,
          "datasetRowsTested": 1
        },
        "aggregate_diff": {
          "diff": 1,
          "diffPercent": 1,
          "function": "text",
          "sourceCheckRowsTested": 1,
          "sourceDatasetRowsTested": 1,
          "sourceValue": 1,
          "targetCheckRowsTested": 1,
          "targetDatasetRowsTested": 1,
          "targetValue": 1
        },
        "duplicate": {
          "checkRowsTested": 1,
          "datasetRowsTested": 1,
          "failedRowsCount": 1,
          "failedRowsDataQuery": "text",
          "failedRowsKeysQuery": "text",
          "failedRowsPercent": 1,
          "failedRowsSourceQuery": "text",
          "missingCount": 1
        },
        "duplicate_diff": {
          "duplicateCountDiff": 1,
          "duplicateDiffPercent": 1,
          "sourceCheckRowsTested": 1,
          "sourceDatasetRowsTested": 1,
          "sourceDuplicateCount": 1,
          "targetCheckRowsTested": 1,
          "targetDatasetRowsTested": 1,
          "targetDuplicateCount": 1
        },
        "failed_rows": {
          "checkRowsTested": 1,
          "datasetRowsTested": 1,
          "failedRowsCount": 1,
          "failedRowsDataQuery": "text",
          "failedRowsKeysQuery": "text",
          "failedRowsPercent": 1,
          "failedRowsSourceQuery": "text"
        },
        "freshness": {
          "actualTimestamp": "2026-01-01T00:00:00.000Z",
          "actualTimestampUtc": "2026-01-01T00:00:00.000Z",
          "datasetRowsTested": 1,
          "expectedTimestamp": "2026-01-01T00:00:00.000Z",
          "expectedTimestampUtc": "2026-01-01T00:00:00.000Z"
        },
        "freshness_diff": {
          "freshnessDiff": 1,
          "freshnessDiffUnit": "minutes",
          "sourceCheckRowsTested": 1,
          "sourceDatasetRowsTested": 1,
          "sourceMaxTimestamp": "2026-01-01T00:00:00.000Z",
          "sourceMaxTimestampUtc": "2026-01-01T00:00:00.000Z",
          "targetCheckRowsTested": 1,
          "targetDatasetRowsTested": 1,
          "targetMaxTimestamp": "2026-01-01T00:00:00.000Z",
          "targetMaxTimestampUtc": "2026-01-01T00:00:00.000Z"
        },
        "fuzzy_duplicate": {
          "candidateRowsScored": 1,
          "checkRowsTested": 1,
          "clusterCount": 1,
          "datasetRowsTested": 1,
          "failedRowsCount": 1,
          "failedRowsDataQuery": "text",
          "failedRowsKeysQuery": "text",
          "failedRowsSourceQuery": "text",
          "fuzzyDuplicateCount": 1,
          "fuzzyDuplicatePercent": 1,
          "meanConfidence": 1
        },
        "group_by": {
          "diagnosticsCount": 1,
          "failedRowsDataQuery": "text",
          "failedRowsKeysQuery": "text",
          "failedRowsSourceQuery": "text",
          "groups": [
            {
              "group": "text",
              "rowsTested": 1,
              "status": "pass",
              "value": 1
            }
          ]
        },
        "hierarchy": {
          "brokenPathCount": 1,
          "checkRowsTested": 1,
          "datasetRowsTested": 1,
          "failedRowsCount": 1,
          "failedRowsDataQuery": "text",
          "failedRowsKeysQuery": "text",
          "failedRowsSourceQuery": "text",
          "invalidValueCount": 1,
          "missingValueCount": 1
        },
        "invalid": {
          "checkRowsTested": 1,
          "datasetRowsTested": 1,
          "failedRowsCount": 1,
          "failedRowsDataQuery": "text",
          "failedRowsKeysQuery": "text",
          "failedRowsPercent": 1,
          "failedRowsSourceQuery": "text",
          "missingCount": 1
        },
        "llm": {
          "completionTokens": 1,
          "failedRowsCount": 1,
          "failedRowsDataQuery": "text",
          "failedRowsKeysQuery": "text",
          "failedRowsSourceQuery": "text",
          "model": "text",
          "promptTokens": 1,
          "rowsChecked": 1,
          "rowsFailed": 1,
          "rowsFailedPercent": 1,
          "tokensSpent": 1
        },
        "metric": {
          "datasetRowsTested": 1
        },
        "metric_diff": {
          "metricDiff": 1,
          "metricDiffPercent": 1,
          "sourceCheckRowsTested": 1,
          "sourceDatasetRowsTested": 1,
          "sourceMetric": 1,
          "targetCheckRowsTested": 1,
          "targetDatasetRowsTested": 1,
          "targetMetric": 1
        },
        "missing": {
          "checkRowsTested": 1,
          "datasetRowsTested": 1,
          "failedRowsCount": 1,
          "failedRowsDataQuery": "text",
          "failedRowsKeysQuery": "text",
          "failedRowsPercent": 1,
          "failedRowsSourceQuery": "text"
        },
        "reference_diff": {
          "diffCount": 1,
          "diffPercent": 1,
          "exclusiveInSource": 1,
          "exclusiveInTarget": 1,
          "sourceCheckRowsTested": 1,
          "sourceDatasetRowsTested": 1,
          "targetCheckRowsTested": 1,
          "targetDatasetRowsTested": 1
        },
        "row_count": {
          "checkRowsTested": 1,
          "datasetRowsTested": 1
        },
        "row_count_diff": {
          "rowCountDiff": 1,
          "rowCountDiffPercent": 1,
          "sourceCheckRowsTested": 1,
          "sourceDatasetRowsTested": 1,
          "targetCheckRowsTested": 1,
          "targetDatasetRowsTested": 1
        },
        "rows_diff": {
          "changed": 1,
          "diffCount": 1,
          "diffPercent": 1,
          "exclusiveInSource": 1,
          "exclusiveInTarget": 1,
          "nullKeyRowsSource": 1,
          "nullKeyRowsTarget": 1,
          "sourceCheckRowsTested": 1,
          "sourceDatasetRowsTested": 1,
          "targetCheckRowsTested": 1,
          "targetDatasetRowsTested": 1
        },
        "schema": {
          "actual": [
            {
              "name": "text",
              "type": "text"
            }
          ],
          "expected": [
            {
              "name": "text",
              "type": "text"
            }
          ]
        },
        "schema_diff": {
          "missingInSource": [
            {
              "name": "text",
              "type": "text"
            }
          ],
          "missingInTarget": [
            {
              "name": "text",
              "type": "text"
            }
          ],
          "typeMismatch": [
            {
              "sourceColumn": "text",
              "sourceType": "text",
              "targetColumn": "text",
              "targetType": "text"
            }
          ]
        }
      },
      "evaluationStatus": "pass",
      "feedback": {
        "freeTextReason": "text",
        "isCorrectlyClassified": true,
        "reason": "expectedDailySeasonality",
        "skipMeasurements": "previous",
        "submittedAt": "2026-01-01T00:00:00.000Z"
      },
      "id": "text",
      "incident": {
        "cloudUrl": "text",
        "id": "text",
        "name": "text",
        "number": 1,
        "status": "reported"
      },
      "measure": "time",
      "scanId": "text",
      "scanTime": "2026-01-01T00:00:00.000Z",
      "value": 1,
      "valueLabel": "text",
      "valueSeries": {
        "values": [
          {
            "label": "text",
            "level": "pass",
            "value": 1
          }
        ]
      }
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}
PreviousAttributes
NextContracts

Last updated

Was this helpful?