Sign in
Sources

Retrieve a scan's live progress

⚠️ Beta endpoint: behavior and schemas are subject to change.

Retrieve the live progress of a historical scan: a coarse status (queued, in_progress, completed) plus element and byte counters, which keep reporting the scan's final tally once it completes.

Counters are reported the same way for every source, but not every source tracks every counter: data_downloaded_bytes and data_scanned_bytes are null for sources that do not measure bytes (VCS repositories among them), which is distinct from a real 0.

Poll this endpoint instead of the scan detail endpoint while a scan is running. Once the scan reaches completed, the response includes an audit_url pointing at the scan's audit summary; stop polling and fetch that endpoint instead.

elements_total is provisional while listing_finished is false — it only reflects elements listed so far, not the final total.

get/v1/scans/{scan_id}/live-progress

Path parameters

scan_idstring uuid required

The id of the scan to retrieve the live progress of.

Response

Scan live progress

status'queued' | 'in_progress' | 'completed' required

Coarse live-progress phase of the scan.

audit_urlstring nullable

URL of the scan's audit summary. Only present once status is completed.

elements_scannedinteger nullable

Number of elements scanned so far. Once status is completed this is the scan's final count.

elements_totalinteger nullable

Number of elements listed so far. Provisional (still growing) until listing_finished is true. Once status is completed this is the scan's final count.

listing_finishedboolean nullable

Whether the scan has finished listing all its elements, i.e. whether elements_total reflects the true final count.

elements_skippedinteger nullable

Number of elements skipped so far. Once status is completed this is the scan's final count.

elements_failedinteger nullable

Number of elements that failed to scan so far. Once status is completed this is the scan's final count.

data_downloaded_bytesinteger nullable

Amount of data downloaded so far, in bytes. Once status is completed this is the scan's final total. null for sources that do not track byte counters.

data_scanned_bytesinteger nullable

Amount of data scanned so far, in bytes. Once status is completed this is the scan's final total. null for sources that do not track byte counters.

Example response

{
  "status": "in_progress",
  "audit_url": "/v1/scans/3fa85f64-5717-4562-b3fc-2c963f66afa6/audit",
  "elements_scanned": 128,
  "elements_total": 512,
  "elements_skipped": 3,
  "data_downloaded_bytes": 10485760,
  "data_scanned_bytes": 10485760
}

Changes