Skip to content

Get a single scan's status and detail

View .md
GET
/projects/{projectId}/scans/{scanId}
curl --request GET \
--url https://zkao.io/api/v1/projects/example/scans/example \
--header 'Authorization: Bearer <token>'

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.

projectId
required
string
scanId
required
string

OK

Media typeapplication/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:

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
budget
One of:

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
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
minCredits
required
integer
recommendedCredits
required
integer
maxCredits
required
integer
branch
string | null
creditBudget

Reserved budget for the scan, in credits.

integer | null
findingsSummary
object
total
integer
bySeverity
object
key
additional properties
integer
Example
{
"scan": {
"status": "QUEUED",
"failureCode": "NO_MEMBER_REPO_ACCESS",
"effort": "medium",
"budget": {
"nextBudgetRecommendation": "keep"
},
"triage": {
"status": "pending"
}
}
}
Retry-After
integer

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

Missing, malformed, expired, or revoked token

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

The token lacks the required scope

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

Resource not in this token’s project or repo allowlist

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}

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.

Media typeapplication/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
{
"error": {
"code": "unauthorized"
}
}
Retry-After
integer

Seconds to wait before retrying.