# List scans (most recent first)

GET

/projects/{projectId}/scans

```js
const url = 'https://zkao.io/api/v1/projects/example/scans?page=1&limit=50';
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?page=1&limit=50' \
  --header 'Authorization: Bearer <token>'
```

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

Requires scope: `read`.

## Authorizations

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

## Parameters

### Path Parameters

* **projectId**

  required

  string

### Query Parameters

* **page**

  integer

  default: 1 >= 1

* **limit**

  integer

  default: 50 >= 1 <= 100

## Responses

### 200

OK

application/json

object

* **items**

  required

  Array\<object>

  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

* **page**

  required

  integer

* **limit**

  required

  integer

* **total**

  required

  integer

##### Example

```json
{
  "items": [
    {
      "status": "QUEUED",
      "failureCode": "NO_MEMBER_REPO_ACCESS",
      "effort": "medium",
      "budget": {
        "nextBudgetRecommendation": "keep"
      }
    }
  ]
}
```

### 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"
  }
}
```
