# Get a single scan's status and detail

GET

/projects/{projectId}/scans/{scanId}

```js
const url = 'https://zkao.io/api/v1/projects/example/scans/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
curl --request GET \
  --url https://zkao.io/api/v1/projects/example/scans/example \
  --header 'Authorization: Bearer <token>'
```

* Production`zkao.io/api/v1/projects/{projectId}/scans/{scanId}`
* Staging`staging.zkao.io/api/v1/projects/{projectId}/scans/{scanId}`

Requires scope: `read`. Use for polling a launched scan. While the scan is not yet terminal the response carries an advisory `Retry-After` header telling you how long to wait before polling again; respect it (and back off on `429`) instead of polling in a tight loop.

## Authorizations

* **[bearerAuth](https://docs.zkao.io/api/#bearerauth)**

## Parameters

### Path Parameters

* **projectId**

  required

  string

* **scanId**

  required

  string

## Responses

### 200

OK

application/json

object

* **scan**

  required

  object

  * **id**

    required

    string

  * **status**

    required

    string

    Allowed values: QUEUED PROCESSING COMPLETED FAILED CANCELLED

  * **failureCode**

    An actionable setup failure for a failed scan. Null for other statuses and internal failures. Restore a project member’s GitHub access or approve the App permissions before launching again.

    string | null

    Allowed values: NO_MEMBER_REPO_ACCESS GITHUB_APP_PERMISSIONS_PENDING

  * **repositoryId**

    required

    string

  * **commitHash**

    string | null

  * **baseCommit**

    A diff scan’s base, as the merge base SHA its change is measured from. Null for other scans.

    string | null

  * **commitMessage**

    string | null

  * **presetName**

    string | null

  * **effort**

    The scan’s budget measured against the levels sized for its scope at launch. `high` starts at the recommended baseline, `extra-high` at the next level, and `deep` at the highest level. The server accounts for the scan limit and any fixed setup cost when sizing these levels. `medium` records a custom budget below High or a historical scan at that level. Null for a Flash scan and for a scan with no recorded effort.

    string | null

    Allowed values: medium high extra-high deep

  * **createdAt**

    required

    string format: date-time

  * **startedAt**

    string | null format: date-time

  * **completedAt**

    string | null format: date-time

  * **progress**

    One of:

    object

    How far a running scan has got through its phases. Deliberately not a time estimate: a phase’s duration moves with the guidance it was given, the repository, and the model that ran it.

    object

    * **phasesCompleted**

      required

      Phases that reached a terminal state (completed, failed, or skipped).

      integer

    * **phasesTotal**

      required

      Phases this scan will run, fixed when it was dispatched.

      integer

    * **percent**

      required

      Weighted completion. Each phase counts for its share of the scan budget, so this does not simply equal phasesCompleted / phasesTotal.

      integer

      <= 100

    null

    null

  * **budget**

    One of:

    object

    What a scan was allowed to spend, what it was charged, and whether the next scan of its type and scope should get more. Check the last scan of a type before choosing the next one’s budget.

    object

    * **limitCredits**

      required

      The most the scan could spend, in credits.

      integer

    * **spentCredits**

      required

      Credits charged for the scan. Null until it finishes.

      integer | null

    * **nextBudgetRecommendation**

      required

      Whether the next scan of this type and scope should keep this budget or raise it. A raise is half again, never above twice the scan type’s minimum. A raise can follow a scan that spent well under its limit: the limit is divided between the parts of the analysis, and one part cannot use another’s unspent share. Null until the scan completes.

      string | null

      Allowed values: keep raise

    null

    null

  * **triage**

    required

    Completeness of triage, independent of whether the scan succeeded.

    object

    * **status**

      required

      string

      Allowed values: pending running complete budget_exhausted blocked

    * **untriagedCount**

      required

      integer

    * **activeRunId**

      required

      string | null

    * **resume**

      required

      Any of:

      object

      object

      * **minCredits**

        required

        integer

      * **recommendedCredits**

        required

        integer

      * **maxCredits**

        required

        integer

      null

      null

  * **branch**

    string | null

  * **creditBudget**

    Reserved budget for the scan, in credits.

    integer | null

  * **findingsSummary**

    object

    * **total**

      integer

    * **bySeverity**

      object

      * **_key_**

        additional properties

        integer

##### Example

```json
{
  "scan": {
    "status": "QUEUED",
    "failureCode": "NO_MEMBER_REPO_ACCESS",
    "effort": "medium",
    "budget": {
      "nextBudgetRecommendation": "keep"
    },
    "triage": {
      "status": "pending"
    }
  }
}
```

#### Headers

* **Retry-After**

  integer

  Advisory seconds to wait before polling again. Present only while the scan is still running (not for terminal scans).

### 401

Missing, malformed, expired, or revoked token

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 403

The token lacks the required scope

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 404

Resource not in this token’s project or repo allowlist

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 429

Rate limited. Either the token’s spend limit for the current period is reached (on launch), or the token is sending too many requests. Wait the number of seconds in the `Retry-After` header before retrying.

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

#### Headers

* **Retry-After**

  integer

  Seconds to wait before retrying.
