Get a single scan's status and detail
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);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Responses
Section titled “ Responses ”OK
object
object
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.
A diff scan’s base, as the merge base SHA its change is measured from. Null for other scans.
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.
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
Phases that reached a terminal state (completed, failed, or skipped).
Phases this scan will run, fixed when it was dispatched.
Weighted completion. Each phase counts for its share of the scan budget, so this does not simply equal phasesCompleted / phasesTotal.
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
The most the scan could spend, in credits.
Credits charged for the scan. Null until it finishes.
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.
Reserved budget for the scan, in credits.
object
object
Example
{ "scan": { "status": "QUEUED", "failureCode": "NO_MEMBER_REPO_ACCESS", "effort": "medium", "budget": { "nextBudgetRecommendation": "keep" }, "triage": { "status": "pending" } }}Headers
Section titled “Headers”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
object
object
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.
Example
{ "error": { "code": "unauthorized" }}The token lacks the required scope
object
object
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.
Example
{ "error": { "code": "unauthorized" }}Resource not in this token’s project or repo allowlist
object
object
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.
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.
object
object
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.
Example
{ "error": { "code": "unauthorized" }}Headers
Section titled “Headers”Seconds to wait before retrying.
