# Run scans

A scan audits one commit of one repository. You choose the scan type and a credit budget. zkao reserves the budget, runs the analysis, and records findings on the project.

The TypeScript examples use a client created as shown in the [SDK reference](https://docs.zkao.io/reference/sdk/). The curl examples assume `ZKAO_API_TOKEN` and `ZKAO_PROJECT_ID` are set.

## The flow

1. Find the repository and check that it is ready.
2. Pick a scan type (a preset).
3. Launch the scan with a budget.
4. Wait for it to finish.
5. Read its findings. See [Triage findings](https://docs.zkao.io/guides/findings/).

## Find a repository

List the repositories in the project. A token restricted to some repositories only sees those.

CLI

```bash
zkao repos
```

TypeScript

```ts
const repositories = await zkao.listRepositories();
```

curl

```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories
```

Each repository has a `readiness` field. A repository added moments ago is `analyzing`. zkao makes a one-time pass over it first, and that pass costs no credits. A launch during that pass fails with `409 repository_initializing`.

Wait for `ready` instead of retrying the launch.

CLI

```bash
zkao repos:wait <repoId>
```

TypeScript

```ts
await zkao.waitForRepositoryReady(repoId);
```

curl

```bash
# Poll until the repository reports "readiness": "ready".
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories
```

The SDK waits up to 30 minutes by default. It backs off between polls and honors `Retry-After`.

## Pick a scan type

A preset is a scan type. Each one runs a fixed set of analyses. Broader types run more analysis and need a larger budget.

CLI

```bash
zkao presets
```

TypeScript

```ts
const presets = await zkao.listScanPresets();
```

curl

```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scan-presets
```

The builtin presets come in two tiers. Flash runs one focused analysis, led by a flagship model when it audits the code or a change. Max runs every technique on flagship models. Each tier has a preset for the code (`builtin:Flash`, `builtin:Max`), a change (`builtin:Flash Diff`, `builtin:Max Diff`), open findings (`builtin:Flash Retriage`, `builtin:Max Retriage`), and resolved findings (`builtin:Flash Regression Check`, `builtin:Max Regression Check`). Earlier names still resolve.

Each preset has a `ref`, a `name`, a `description`, and a `minCredits` floor. Pass the `ref` when you launch. Without one, the launch uses the first active preset.

## Choose a budget

The budget is the most a scan may spend, in credits. zkao reserves it at launch and never charges more. Credits the scan does not use go back to the balance.

You can leave the budget out. zkao then picks the budget it recommends for this scan type and scope on this repository. The recommendation follows what past scans of the repository spent. The first scan of a repository starts at the scan type’s minimum. A diff scan is sized from its change instead, up to three times the minimum. The launch response tells you which budget was used.

A scan that runs short of budget stops early, so treat its coverage as partial. See [Credits and usage](https://docs.zkao.io/guides/credits/) for how reservations affect the balance.

## Launch a scan

CLI

```bash
zkao scans launch --repo <repoId> --preset <ref> --budget 500
```

TypeScript

```ts
const { scanId, creditBudget } = await zkao.launchScan({
  repositoryId: repoId,
  presetRef: ref,
  creditBudget: 500,
});
```

curl

```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repositoryId":"<repoId>","presetRef":"<ref>","creditBudget":500}' \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans
```

The API answers `202` with `scanId`, `queued`, `creditBudget`, and `buildsOverview`. Launching needs the `scans:launch` scope.

### Choose the commit

By default a scan runs on the head of the repository’s default branch.

* `branch` scans the head of that branch, resolved when the scan launches.
* `commitHash` pins one commit (7 to 40 hex characters). It wins over `branch`.
* `commitMessage` is optional metadata shown with the scan.

The CLI flags are `--branch`, `--commit`, and `--message`. The commit must be pushed to GitHub, because zkao reads it from there.

### Scope a scan to audit areas

An audit area is a named subsystem of the repository. zkao discovers areas when it maps the code. You can add your own. Scoping a scan to a few areas keeps a large repository affordable.

CLI

```bash
zkao areas list <repoId>
zkao scans launch --repo <repoId> --preset "builtin:Max" --area <key> --area <otherKey>
```

TypeScript

```ts
const { areas } = await zkao.listAuditAreas(repoId);
await zkao.launchScan({
  repositoryId: repoId,
  presetRef: "builtin:Max",
  auditAreaKeys: [areas[0].key],
});
```

curl

```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories/<repoId>/audit-areas
```

Each area reports its size in files and lines from one branch’s map. Pass `--branch` (or `branch`) to read another branch’s sizes.

Leave the area list out to scan the whole repository. Or describe the code to audit in your own words with `--scope` (or `auditScope`). A key the current map no longer names fails the launch. zkao never drops it silently, so a budget sized for one area never runs against everything.

An area is a name and a description, never a file list. Each scan resolves it against the code at its own commit.

CLI

```bash
zkao areas add <repoId> "Proof verifier" --description "On-chain verifier and its key loading"
zkao areas rm <repoId> <areaKey>
```

TypeScript

```ts
const area = await zkao.createAuditArea(
  repoId,
  "Proof verifier",
  "On-chain verifier and its key loading",
);
await zkao.deleteAuditArea(repoId, area.key);
```

curl

```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Proof verifier","description":"On-chain verifier and its key loading"}' \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/repositories/<repoId>/audit-areas
```

Adding and deleting areas needs the `guidance:write` scope. Only custom areas can be deleted. Deleting a discovered area returns `409`.

### Guide one scan

Guidance tells a scan what matters: scope, threat model, and accepted risks. A launch can carry guidance for that scan only. It replaces the repository’s stored guidance for this run. A `zkao.md` committed in the repository still applies underneath.

CLI

```bash
zkao scans launch --repo <repoId> --guidance focus.md
cat focus.md | zkao scans launch --repo <repoId> --guidance -
```

TypeScript

```ts
await zkao.launchScan({
  repositoryId: repoId,
  guidance: "Focus on the proof verifier. The prover is trusted.",
});
```

curl

```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repositoryId":"<repoId>","guidance":"Focus on the proof verifier."}' \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans
```

In the API, the `guidance` field has three states:

* Left out: the scan uses the repository’s stored guidance.
* A string: that text replaces it for this scan.
* `null` or an empty string: the scan runs with no stored guidance layer.

Guidance is limited to 100,000 characters. See [Repository guidance](https://docs.zkao.io/guides/guidance/) for the standing layer.

## Follow a scan

A scan moves through these statuses:

| Status       | Meaning                                                  |
| ------------ | -------------------------------------------------------- |
| `QUEUED`     | Accepted and waiting to start.                           |
| `PROCESSING` | Running.                                                 |
| `COMPLETED`  | Analysis finished. Check `triage` for unfinished review. |
| `FAILED`     | Stopped on an error.                                     |
| `CANCELLED`  | Cancelled before it finished.                            |

The last three are terminal.

While a scan runs, its `progress` field reports `phasesCompleted`, `phasesTotal`, and a weighted `percent`. There is no time estimate. How long a scan takes depends on the repository and its guidance. A finished scan carries a `findingsSummary` with counts by severity.

The easiest way to follow a scan is to wait on it.

CLI

```bash
zkao scans wait <scanId>
zkao scans wait <scanId> --timeout 7200
```

TypeScript

```ts
const scan = await zkao.waitForScan(scanId, {
  onPoll: (s) => console.log(s.status, s.progress?.percent),
});
```

curl

```bash
curl -i -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans/<scanId>
```

`zkao scans wait` prints each poll on stderr and the final scan as JSON on stdout. Its `--timeout` is in seconds. The SDK’s `waitForScan` gives up after one hour by default. Set `timeoutMs` for longer scans, and pass a `signal` to abort.

### Poll politely

If you poll by hand, read the `Retry-After` header on the scan response. It says how many seconds to wait before the next poll. It is present only while the scan is not terminal.

A token that polls too fast gets `429 rate_limited`, also with `Retry-After`. Wait that long before the next request. The CLI and SDK do this for you.

Tip

Prefer `zkao scans wait` or `waitForScan` over your own loop. They back off with jitter and treat `429` as a signal to slow down, not as an error.

## Resume unfinished triage

A completed scan can have findings that triage did not review. Unreviewed findings are withheld from results. Read `triage` on the scan detail before treating it as a complete review.

| Field            | Meaning                                                             |
| ---------------- | ------------------------------------------------------------------- |
| `status`         | `pending`, `running`, `complete`, `budget_exhausted`, or `blocked`. |
| `untriagedCount` | Findings still awaiting review.                                     |
| `activeRunId`    | Active triage run, or `null`.                                       |
| `resume`         | Allowed credit budgets after a budget stop, or `null`.              |

Resumption is available after a budget stop on a completed scan whose billing has settled. Unfinished findings must remain and no triage run may be active. Choose a budget within the offer and your authorized spending limit. Resumed triage uses the scan’s settings and only reviews the findings left over. It reserves a separate budget and returns unused credits.

CLI

```bash
zkao scans get <scanId>
zkao scans resume-triage <scanId> --budget <credits> --idempotency-key <key>
zkao scans triage-wait <scanId> <runId>
zkao scans get <scanId>
```

TypeScript

```ts
const { run } = await zkao.resumeTriage(
  scanId,
  { creditBudget: authorizedCredits },
  { idempotencyKey: requestKey },
);
await zkao.waitForTriageRun(scanId, run.id);
const scan = await zkao.getScan(scanId);
console.log(scan.triage);
```

curl

```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <key>" \
  -d '{"creditBudget":250}' \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans/<scanId>/triage/resume
```

Resumption needs `scans:launch` and respects the token’s repository and spending limits. Keep the same key and budget when retrying the same request. That returns the original run without reserving another budget. A different budget with that key returns `409`. Use a new key only for another authorized run.

The parent scan stays `COMPLETED` while resumed triage runs. Poll the returned run with `getTriageRun` or its CLI counterpart. Read the scan’s `triage` again after the run finishes. A run can finish at its budget cap with findings still awaiting review. For a `blocked` triage status, contact support with a link to the scan.

## List scans

Scans are listed newest first. The list is paginated with `page` and `limit` (at most 100, default 50).

CLI

```bash
zkao scans list --limit 20
zkao scans get <scanId>
```

TypeScript

```ts
const { items, total } = await zkao.listScans({ limit: 20 });
const detail = await zkao.getScan(items[0].id);
```

curl

```bash
curl -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  "https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans?limit=20"
```

## Cancel a scan

You can cancel a queued or running scan. zkao stops its work, marks it `CANCELLED`, and releases its reserved credits. Work already in flight settles what it actually spent as it winds down.

CLI

```bash
zkao scans cancel <scanId>
```

TypeScript

```ts
await zkao.cancelScan(scanId);
```

curl

```bash
curl -X POST -H "Authorization: Bearer $ZKAO_API_TOKEN" \
  https://zkao.io/api/v1/projects/$ZKAO_PROJECT_ID/scans/<scanId>/cancel
```

Cancelling needs the `scans:launch` scope. A scan that already reached `COMPLETED` or `FAILED` cannot be cancelled and returns `400`.

## Launch errors

| Status | Code                      | What to do                                                                                |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------- |
| `400`  | `bad_request`             | Fix the request. The message names the problem.                                           |
| `400`  | `diff_base_*`             | See [Diff scans](https://docs.zkao.io/guides/diff-scans/).                                |
| `402`  | `insufficient_credits`    | Add credits, or launch with a smaller budget.                                             |
| `403`  | `forbidden`               | The token lacks `scans:launch`.                                                           |
| `404`  | `not_found`               | The repository is outside the token’s project or repository allowlist.                    |
| `409`  | `repository_initializing` | Wait for the repository to be `ready`.                                                    |
| `422`  | `diff_empty`              | The diff scan has nothing to audit.                                                       |
| `429`  | `rate_limited`            | The token’s spend limit is reached, or it sent too many requests. Wait for `Retry-After`. |

The full contract is in the API reference for [launchScan](https://docs.zkao.io/api/operations/launchscan/) and [getScan](https://docs.zkao.io/api/operations/getscan/).
