---
title: "Get scan status"
method: GET
path: "/api/v1/scans/{scanId}"
tags: ["Scans"]
---

# Get scan status

`GET /api/v1/scans/{scanId}`

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.

- `queuing`: The scan is in the queue for execution, awaiting a pick-up from a Soda Runner.

- `executing`: A Soda Runner has picked up the scan and is executing.

- `cancelationRequested`: An entity requested cancelation of this scan and the request is awaiting pick-up from the Soda Runner responsible for the scan.

- `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.

- `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 a final state of a 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

## Path parameters

- `scanId` string, required

## Response `200`

Successful response

- PublicApiScanStatusResponse
  - `agentId` string
  - `checks` PublicApiCheckSlimDTO[]
    - `evaluationStatus` 'pass' | 'warn' | 'fail' | 'notEvaluated' | 'excluded'
    - `id` string
  - `cloudUrl` string, required
  - `contractDatasetCloudUrl` string
  - `created` string, date-time, required
  - `ended` string, date-time
  - `errors` integer
  - `failures` integer
  - `id` string, required
  - `postProcessingStages` PublicApiPostProcessingStageDTO[]
    - `ended` string, date-time
    - `name` 'diagnosticWarehouse', required
    - `started` string, date-time
    - `state` 'ongoing' | 'completed' | 'failed'
  - `runnerId` string
  - `scanDefinition` PublicApiScanDefinitionSlim
    - `id` string, required
    - `name` string, required
  - `scanTime` string, date-time
  - `started` string, date-time
  - `state` 'queuing' | 'executing' | 'started' | 'cancelationRequested' | 'timeOutRequested' | 'canceled' | 'timedOut' | 'failed' | 'completedWithErrors' | 'completedWithFailures' | 'completedWithWarnings' | 'completed', required
  - `submitted` string, date-time
  - `warnings` integer

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error

---

[API](https://skmtc.dev/soda/apis/soda-cloud-api-v4.md) · [All operations](https://skmtc.dev/soda/apis/soda-cloud-api-v4/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/soda/soda-cloud-api-v4/revisions/ce87192b6b72/schema)