> 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/scans.md).

# Scans

Soda Cloud API Scan Endpoints

## List scans

> This endpoint lists the scan runs of your organization, newest first. Use it to find a scan you triggered earlier, to follow the scans of one dataset or datasource over time, or to look up a scan by the reference your Soda Library run printed. Scans that are still running are listed as well.\
> \
> This GET is a paginated API that uses the following parameters to request specific details:\
> \
> \- \`datasetIds\`: Optionally, use this parameter to collect only the scans that covered any of the given datasets. Provide multiple values as a comma-separated list of dataset IDs, which you can find in the URL of each dataset page in Soda Cloud. This query parameter is limited to 100 dataset IDs. Unknown datasets, datasets you cannot view and datasets that are not V4 are ignored.\
> \
> \- \`datasetId\`: \*\*Deprecated\*\*, use \`datasetIds\` instead. Optionally, use this parameter to collect only the scans that covered a specific dataset. It cannot be combined with \`datasetIds\`.\
> \
> \- \`datasourceId\`: Optionally, use this parameter to collect only the scans of a specific datasource.\
> \
> \- \`scanReference\`: Optionally, use this parameter to look up the single scan run with this reference. A Soda Library run prints its scan reference in the scan log.\
> \
> \- \`state\`: Optionally, use this parameter to collect only the scans in one state, such as \`started\` for the scans that are still running or \`completed\` for the ones that finished without warnings or failures.\
> \
> \- \`scanType\`: Optionally, use this parameter to collect only the scans of one type. The type of a scan is the type of the scan definition it ran for, the same type Soda Cloud shows: \`default\` for the scans of a scan definition you created, \`observability\` for the anomaly scans Soda Cloud runs on a dataset, \`contract\` for a contract verification, and so on.\
> \
> \- \`from\`: Collect only the scans whose \`scanTime\` 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 scans whose \`scanTime\` 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\`\
> \
> \- \`includeDatasets\`: Optionally, set this to \`true\` to have every scan carry the datasets it covered. It is \`false\` by default because a scan can cover many datasets.\
> \
> \- \`cursor\`: Omit for the first page. Pass the previous response's \`nextCursor\`, with the same other parameters, to continue after its last item. Cursors are opaque; invalid cursors return 400. When paging through many scans, pass an explicit \`from\` so every page reads the same window.\
> \
> \- \`size\`: Number of items per page, from 1 to 1000, default 100. The size may change between pages.\
> \
> The response contains \`content\` and, when more items are available, \`nextCursor\`. An absent \`nextCursor\` marks the end of the results. Page numbers and totals are not returned.\
> \
> Scans are sorted by \`scanTime\` in descending order, newest first. The list is read from the analytical store, so a scan can take a few seconds to appear after Soda Cloud records it.\
> \
> The scans Soda Cloud runs to test a datasource connection are never listed.\
> \
> \## Authorization\
> \
> Soda only returns the scans of datasources to which the user has \*\*View\*\* permissions. Soda Cloud Admins have access to all scans. \*\*See \[Manage datasource roles]\(<https://go.soda.io/roles-datasource>) 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\
> \
> \`Scans\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Scan Endpoints","name":"Scans"}],"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":{"PublicApiScanTypeDTO":{"type":"string","enum":["default","runnerTest","cicd","discussion","checkDatasourceConnection","uiTest","observability","observabilityBackfilling","profiling","discovery","lineageDiscovery","contract","contractTest","generateContract","generateContractViaAutopilot","onboarding","checkDiagnosticsWarehouseConnection","dataStandards","dataStandardsTest"]},"ScanStateDTO":{"type":"string","enum":["queuing","executing","started","cancelationRequested","timeOutRequested","canceled","timedOut","failed","completedWithErrors","completedWithFailures","completedWithWarnings","completed"]},"PublicApiScansResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ScansContentDTO"}},"nextCursor":{"type":"string"}},"required":["content"]},"ScansContentDTO":{"type":"object","properties":{"cloudUrl":{"type":"string"},"created":{"type":"string","format":"date-time","description":"When Soda Cloud recorded the scan."},"datasets":{"type":"array","description":"The datasets the scan covered. Only filled in when `includeDatasets` is `true`.","items":{"type":"object","$ref":"#/components/schemas/DatasetSlimDTO"}},"ended":{"type":"string","format":"date-time"},"id":{"type":"string"},"runnerId":{"type":"string","description":"The runner that executed the scan. Null for scans that ran outside a runner."},"scanDefinition":{"type":"object","$ref":"#/components/schemas/PublicApiScanDefinitionSlim"},"scanReference":{"type":"string","description":"The reference the runner or the Soda Library reported for this scan run."},"scanTime":{"type":"string","format":"date-time","description":"The timestamp of the data the scan looked at, which can be older than when the scan ran. Results are sorted on this timestamp, newest first, and `from` and `to` filter on it."},"scanType":{"type":"object","$ref":"#/components/schemas/PublicApiScanTypeDTO","description":"The type of the scan definition this scan ran for, which is the type Soda Cloud shows for the scan."},"started":{"type":"string","format":"date-time"},"state":{"type":"object","$ref":"#/components/schemas/ScanStateDTO"}}},"DatasetSlimDTO":{"type":"object","properties":{"cloudUrl":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"qualifiedName":{"type":"string"}}},"PublicApiScanDefinitionSlim":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/scans":{"get":{"description":"This endpoint lists the scan runs of your organization, newest first. Use it to find a scan you triggered earlier, to follow the scans of one dataset or datasource over time, or to look up a scan by the reference your Soda Library run printed. Scans that are still running are listed as well.\n\nThis GET is a paginated API that uses the following parameters to request specific details:\n\n- `datasetIds`: Optionally, use this parameter to collect only the scans that covered any of the given datasets. Provide multiple values as a comma-separated list of dataset IDs, which you can find in the URL of each dataset page in Soda Cloud. This query parameter is limited to 100 dataset IDs. Unknown datasets, datasets you cannot view and datasets that are not V4 are ignored.\n\n- `datasetId`: **Deprecated**, use `datasetIds` instead. Optionally, use this parameter to collect only the scans that covered a specific dataset. It cannot be combined with `datasetIds`.\n\n- `datasourceId`: Optionally, use this parameter to collect only the scans of a specific datasource.\n\n- `scanReference`: Optionally, use this parameter to look up the single scan run with this reference. A Soda Library run prints its scan reference in the scan log.\n\n- `state`: Optionally, use this parameter to collect only the scans in one state, such as `started` for the scans that are still running or `completed` for the ones that finished without warnings or failures.\n\n- `scanType`: Optionally, use this parameter to collect only the scans of one type. The type of a scan is the type of the scan definition it ran for, the same type Soda Cloud shows: `default` for the scans of a scan definition you created, `observability` for the anomaly scans Soda Cloud runs on a dataset, `contract` for a contract verification, and so on.\n\n- `from`: Collect only the scans whose `scanTime` 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`\n\n- `to`: Collect only the scans whose `scanTime` 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`\n\n- `includeDatasets`: Optionally, set this to `true` to have every scan carry the datasets it covered. It is `false` by default because a scan can cover many datasets.\n\n- `cursor`: Omit for the first page. Pass the previous response's `nextCursor`, with the same other parameters, to continue after its last item. Cursors are opaque; invalid cursors return 400. When paging through many scans, pass an explicit `from` so every page reads the same window.\n\n- `size`: Number of items per page, from 1 to 1000, default 100. The size may change between pages.\n\nThe response contains `content` and, when more items are available, `nextCursor`. An absent `nextCursor` marks the end of the results. Page numbers and totals are not returned.\n\nScans are sorted by `scanTime` in descending order, newest first. The list is read from the analytical store, so a scan can take a few seconds to appear after Soda Cloud records it.\n\nThe scans Soda Cloud runs to test a datasource connection are never listed.\n\n## Authorization\n\nSoda only returns the scans of datasources to which the user has **View** permissions. Soda Cloud Admins have access to all scans. **See [Manage datasource roles](https://go.soda.io/roles-datasource) 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`Scans`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/scans","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}},{"deprecated":true,"in":"query","name":"datasetId","schema":{"type":"string"}},{"explode":false,"in":"query","name":"datasetIds","schema":{"type":"array","items":{"type":"string"}},"style":"form"},{"in":"query","name":"datasourceId","schema":{"type":"string"}},{"in":"query","name":"from","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"includeDatasets","schema":{"type":"boolean"}},{"in":"query","name":"scanReference","schema":{"type":"string"}},{"in":"query","name":"scanType","schema":{"type":"object","$ref":"#/components/schemas/PublicApiScanTypeDTO"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"state","schema":{"type":"object","$ref":"#/components/schemas/ScanStateDTO"}},{"in":"query","name":"to","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiScansResponse"}}},"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"},"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 scans","tags":["Scans"]}}}}
```

## Get scan status

> This endpoint enables you to check on the state of a scan that you executed using the \*\*Trigger a scan\*\* endpoint. Call this endpoint to monitor the status of a scan during its execution.\
> \
> If you wish to access the logs of a completed scan, use the \*\*Get scan logs\*\* endpoint.\
> \
> This POST uses the following parameter to provide specific details:\
> \
> \- \`scanId\`: Use the value of \`X-Soda-Scan-Id\` returned as part of the \`201\` response when you called the \*\*Trigger a scan\*\* endpoint.\
> \
> As a scan executes, you can call this endpoint to progressively collect values based on the state of the scan. Refer to the list below for the states that calls to this endpoint return.\
> \
> A scan usually goes from \`queuing\` to \`executing\` to \`started\`, and then to a final state. It can skip \`executing\` or \`started\`, so keep calling this endpoint until the scan reaches a final state.\
> \
> \- \`queuing\`: The scan is in the queue for execution, awaiting a pick-up from a Soda Runner. This is not a final state.\
> \
> \- \`executing\`: A Soda Runner has picked up the scan, but the scan has not reported its start yet. This is not a final state.\
> \
> \- \`started\`: The scan has reported its start and is running. The \`started\` field holds the start time. This is not a final state.\
> \
> \- \`cancelationRequested\`: An entity requested cancelation of this scan and the request is awaiting pick-up from the Soda Runner responsible for the scan. This is not a final state.\
> \
> \- \`timeOutRequested\`: A time out has been detected, and an automatic request to stop the scan execution is awaiting pick-up from the Soda Runner responsible for the scan. This is not a final state.\
> \
> \- \`canceled\`: A Soda Runner confirmed that the scan has been cancelled. This is the final state of the scan.\
> \
> \- \`timedOut\`: A Soda Runner confirmed that the scan has timed-out. This is the final state of the scan.\
> \
> \- \`failed\`: The scan did not start, or it did not successfully complete because of an unexpected cause. This is the final state of the scan.\
> \
> \- \`completedWithErrors\`: The scan completed successfully, but there were errors involving some of the checks in the scan. This is the final state of the scan.\
> \
> \- \`completedWithFailures\`: The scan completed successfully and reveals failed results for some checks. This is the final state of the scan.\
> \
> \- \`completedWithWarnings\`: The scan completed successfully and reveals warning results for some checks. This is the final state of the scan.\
> \
> \- \`completed\`: The scan completed successfully and reveals passing results for all checks. This is the final state of the scan.\
> \
> To get the logs of the completed scan, please use API \`/api/v1/scans/{scanId}/logs\`.\
> \
> \## 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.\
> \
> \## Authorization\
> \
> Any Soda Cloud user in your organization may execute this query.\
> \
> \## Tags\
> \
> \`Scans\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Scan Endpoints","name":"Scans"}],"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":{"PublicApiScanStatusResponse":{"type":"object","properties":{"agentId":{"type":"string","deprecated":true},"checks":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/PublicApiCheckSlimDTO"}},"cloudUrl":{"type":"string"},"contractDatasetCloudUrl":{"type":"string"},"created":{"type":"string","format":"date-time"},"ended":{"type":"string","format":"date-time"},"errors":{"type":"integer","format":"int32","description":"Number of scan-level errors. Does not count ERROR-level log entries and may be zero even when the state reports errors or failure."},"failureReason":{"type":"string","description":"Failure diagnostic for scans in the failed state, including when no scan logs are available."},"failures":{"type":"integer","format":"int32"},"id":{"type":"string"},"postProcessingStages":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/PublicApiPostProcessingStageDTO"}},"runnerId":{"type":"string"},"scanDefinition":{"type":"object","$ref":"#/components/schemas/PublicApiScanDefinitionSlim"},"scanTime":{"type":"string","format":"date-time"},"started":{"type":"string","format":"date-time"},"state":{"type":"object","$ref":"#/components/schemas/ScanStateDTO","description":"Scan lifecycle and outcome. Determined independently of errors; the error count alone does not determine the state."},"submitted":{"type":"string","format":"date-time"},"warnings":{"type":"integer","format":"int32"}},"required":["cloudUrl","created","id","state"]},"PublicApiCheckSlimDTO":{"type":"object","properties":{"evaluationStatus":{"type":"object","$ref":"#/components/schemas/EvaluationStatusDTO"},"id":{"type":"string"},"source":{"type":"object","$ref":"#/components/schemas/CheckSourceDTO","description":"Where the check was defined. Null for checks whose source is not known to Soda Cloud."}}},"EvaluationStatusDTO":{"type":"string","enum":["pass","warn","fail","notEvaluated","excluded"]},"CheckSourceDTO":{"type":"string","enum":["soda-sql","soda-core","soda-library","soda-cloud","dbt","soda-contract","data-standard","soda-metric-monitoring"]},"PublicApiPostProcessingStageDTO":{"type":"object","properties":{"ended":{"type":"string","format":"date-time"},"name":{"type":"object","$ref":"#/components/schemas/PublicApiPostProcessingStageTypeDTO"},"started":{"type":"string","format":"date-time"},"state":{"type":"object","$ref":"#/components/schemas/PublicApiPostProcessingStageStateDTO"}},"required":["name"]},"PublicApiPostProcessingStageTypeDTO":{"type":"string","enum":["diagnosticWarehouse"]},"PublicApiPostProcessingStageStateDTO":{"type":"string","enum":["ongoing","completed","failed"]},"PublicApiScanDefinitionSlim":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"ScanStateDTO":{"type":"string","enum":["queuing","executing","started","cancelationRequested","timeOutRequested","canceled","timedOut","failed","completedWithErrors","completedWithFailures","completedWithWarnings","completed"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/scans/{scanId}":{"get":{"description":"This endpoint enables you to check on the state of a scan that you executed using the **Trigger a scan** endpoint. Call this endpoint to monitor the status of a scan during its execution.\n\nIf you wish to access the logs of a completed scan, use the **Get scan logs** endpoint.\n\nThis POST uses the following parameter to provide specific details:\n\n- `scanId`: Use the value of `X-Soda-Scan-Id` returned as part of the `201` response when you called the **Trigger a scan** endpoint.\n\nAs a scan executes, you can call this endpoint to progressively collect values based on the state of the scan. Refer to the list below for the states that calls to this endpoint return.\n\nA scan usually goes from `queuing` to `executing` to `started`, and then to a final state. It can skip `executing` or `started`, so keep calling this endpoint until the scan reaches a final state.\n\n- `queuing`: The scan is in the queue for execution, awaiting a pick-up from a Soda Runner. This is not a final state.\n\n- `executing`: A Soda Runner has picked up the scan, but the scan has not reported its start yet. This is not a final state.\n\n- `started`: The scan has reported its start and is running. The `started` field holds the start time. This is not a final state.\n\n- `cancelationRequested`: An entity requested cancelation of this scan and the request is awaiting pick-up from the Soda Runner responsible for the scan. This is not a final state.\n\n- `timeOutRequested`: A time out has been detected, and an automatic request to stop the scan execution is awaiting pick-up from the Soda Runner responsible for the scan. This is not a final state.\n\n- `canceled`: A Soda Runner confirmed that the scan has been cancelled. This is the final state of the scan.\n\n- `timedOut`: A Soda Runner confirmed that the scan has timed-out. This is the final state of the scan.\n\n- `failed`: The scan did not start, or it did not successfully complete because of an unexpected cause. This is the final state of the scan.\n\n- `completedWithErrors`: The scan completed successfully, but there were errors involving some of the checks in the scan. This is the final state of the scan.\n\n- `completedWithFailures`: The scan completed successfully and reveals failed results for some checks. This is the final state of the scan.\n\n- `completedWithWarnings`: The scan completed successfully and reveals warning results for some checks. This is the final state of the scan.\n\n- `completed`: The scan completed successfully and reveals passing results for all checks. This is the final state of the scan.\n\nTo get the logs of the completed scan, please use API `/api/v1/scans/{scanId}/logs`.\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## Authorization\n\nAny Soda Cloud user in your organization may execute this query.\n\n## Tags\n\n`Scans`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/scans/{scanId}","parameters":[{"in":"path","name":"scanId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiScanStatusResponse"}}},"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":"Get scan status","tags":["Scans"]}}}}
```

## Cancel a scan

> This endpoint enables you to cancel a scan.\
> \
> Depending on the state of the scan when you call this endpoint, the response returns one of the following:\
> \
> \- Where the state is \`pending\`, Soda immediately changes the state to \`canceled\`.\
> \
> \- Where the state is \`submitted\`, Soda immediately changes the state to \`cancelationRequested\`. - Where the scan is in any other state, the endpoint returns a \`400\` (Bad request) response.\
> \
> This DELETE uses the following parameters to provide specific details:\
> \
> \- \`scanId\`: Use the value of \`X-Soda-Scan-Id\` returned as part of the \`201\` response when you called the \*\*Trigger a scan\*\* endpoint.\
> \
> \## 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.\
> \
> \## Authorization\
> \
> Any Soda Cloud user in your organization may execute this query.\
> \
> \## Tags\
> \
> \`Scans\`\
> \
> \## Rate limiting\
> \
> 10 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Scan Endpoints","name":"Scans"}],"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":{"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/scans/{scanId}":{"delete":{"description":"This endpoint enables you to cancel a scan.\n\nDepending on the state of the scan when you call this endpoint, the response returns one of the following:\n\n- Where the state is `pending`, Soda immediately changes the state to `canceled`.\n\n- Where the state is `submitted`, Soda immediately changes the state to `cancelationRequested`. - Where the scan is in any other state, the endpoint returns a `400` (Bad request) response.\n\nThis DELETE uses the following parameters to provide specific details:\n\n- `scanId`: Use the value of `X-Soda-Scan-Id` returned as part of the `201` response when you called the **Trigger a scan** endpoint.\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## Authorization\n\nAny Soda Cloud user in your organization may execute this query.\n\n## Tags\n\n`Scans`\n\n## Rate limiting\n\n10 requests/60 seconds","operationId":"DELETE/api/v1/scans/{scanId}","parameters":[{"in":"path","name":"scanId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","headers":{"Location":{"schema":{"type":"string"}}}},"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":"Cancel a scan","tags":["Scans"]}}}}
```

## Get scan logs

> This endpoint enables you to gather log details about the final state of a scan you executed using the \*\*Trigger a scan\*\* endpoint. Use this endpoint to study scan logs to investigate issues with its execution.\
> \
> If you wish to access the state of a scan in progress, use the \*\*Get scan status\*\* endpoint.\
> \
> This GET is a paginated API that uses the following parameters to request specific details:\
> \
> \- \`scanId\`: Use the value of \`X-Soda-Scan-Id\` returned as part of the \`201\` response when you called the \*\*Trigger a scan\*\* endpoint.\
> \
> \- \`size\`: Supply an integer value between 100 and 1000, inclusive. The default value is 1000.\
> \
> \- \`page\`: Supply an integer value. The default value is 0.\
> \
> \- \`level\`: Optionally, use this parameter to collect only the log lines logged at exactly this level. One of \`debug\`, \`info\`, \`warning\` or \`error\`. It is a single level, not a minimum one, so \`warning\` leaves the errors out.\
> \
> \- \`search\`: Optionally, use this parameter to collect only the log lines whose message contains this text. Letter case is ignored.\
> \
> \- \`from\`: Optionally, use this parameter to collect only the log lines written on or after this moment. Supply an ISO8601 timestamp value. Example: \`2026-08-01T00:00:00+01:00\`\
> \
> \- \`to\`: Optionally, use this parameter to collect only the log lines written on or before this moment. Supply an ISO8601 timestamp value. Example: \`2026-08-01T23:59:59+01:00\`\
> \
> The \`level\`, \`search\`, \`from\` and \`to\` parameters can be combined, and a log line has to match all of the ones you supply (AND). \`totalElements\` and \`totalPages\` count only the log lines that match.\
> \
> The response sorts the the log information by creation timestamp in ascending order.\
> \
> \## 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.\
> \
> \## Authorization\
> \
> Any Soda Cloud user in your organization may execute this query.\
> \
> \## Tags\
> \
> \`Scans\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Scan Endpoints","name":"Scans"}],"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":{"LogLevelDTO":{"type":"string","enum":["debug","info","warning","error"]},"PublicApiScanLogsResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/LogsContentDTO"}},"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"]},"LogsContentDTO":{"type":"object","properties":{"index":{"type":"integer","format":"int32"},"level":{"type":"object","$ref":"#/components/schemas/LogLevelDTO"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}},"required":["index","level","message","timestamp"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/scans/{scanId}/logs":{"get":{"description":"This endpoint enables you to gather log details about the final state of a scan you executed using the **Trigger a scan** endpoint. Use this endpoint to study scan logs to investigate issues with its execution.\n\nIf you wish to access the state of a scan in progress, use the **Get scan status** endpoint.\n\nThis GET is a paginated API that uses the following parameters to request specific details:\n\n- `scanId`: Use the value of `X-Soda-Scan-Id` returned as part of the `201` response when you called the **Trigger a scan** endpoint.\n\n- `size`: Supply an integer value between 100 and 1000, inclusive. The default value is 1000.\n\n- `page`: Supply an integer value. The default value is 0.\n\n- `level`: Optionally, use this parameter to collect only the log lines logged at exactly this level. One of `debug`, `info`, `warning` or `error`. It is a single level, not a minimum one, so `warning` leaves the errors out.\n\n- `search`: Optionally, use this parameter to collect only the log lines whose message contains this text. Letter case is ignored.\n\n- `from`: Optionally, use this parameter to collect only the log lines written on or after this moment. Supply an ISO8601 timestamp value. Example: `2026-08-01T00:00:00+01:00`\n\n- `to`: Optionally, use this parameter to collect only the log lines written on or before this moment. Supply an ISO8601 timestamp value. Example: `2026-08-01T23:59:59+01:00`\n\nThe `level`, `search`, `from` and `to` parameters can be combined, and a log line has to match all of the ones you supply (AND). `totalElements` and `totalPages` count only the log lines that match.\n\nThe response sorts the the log information by creation timestamp in ascending order.\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## Authorization\n\nAny Soda Cloud user in your organization may execute this query.\n\n## Tags\n\n`Scans`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/scans/{scanId}/logs","parameters":[{"in":"path","name":"scanId","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"level","schema":{"type":"object","$ref":"#/components/schemas/LogLevelDTO"}},{"in":"query","name":"page","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"search","schema":{"type":"string"}},{"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/PublicApiScanLogsResponse"}}},"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":"Get scan logs","tags":["Scans"]}}}}
```


---

# 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/scans.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.