Sign in
Sources

Retrieve a scan

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

Retrieve a historical scan's progress: element and byte counters, plus the scan's audit summary once one becomes available.

Poll it while the scan runs, watching report_status rather than scan_status: a scan reaching a terminal status does not mean the audit summary is ready. Stop polling once report_status is done — that response carries the final numbers (duration_seconds, pending_seconds, outcome_by_reason) — or unavailable, meaning no report will ever come for this scan.

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.

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}

Path parameters

scan_idstring uuid required

The id of the scan to retrieve.

Response

Scan progress

scan_idstring uuid required

ID of the scan this progress belongs to.

report_status'pending' | 'in_progress' | 'summarizing' | 'done' | 'unavailable' required

How far the scan's audit report has got. Poll on this, not on scan_status: the scan reaching a terminal status does not mean the report's final numbers (duration_seconds, pending_seconds, outcome_by_reason) are ready yet. Stop polling once report_status is done (the numbers are ready) or unavailable (no report will ever come).

scan_status'launched' | 'pending' | 'running' | 'finished' | 'failed' | 'canceled' | 'too_large' | 'timeout' | 'skipped' | 'pending_timeout' | 'running_failed' | 'running_cancelled' required

Status of the scan itself.

scan_status_reasonstring nullable required

Reason for the scan's current status, e.g. why it failed or was skipped. null when not applicable.

elements_totalinteger required

Number of elements listed so far. Provisional (still growing) until listing_finished is true, after which this is the scan's final count.

elements_scannedinteger required

Number of elements scanned so far. Final once scan_status is terminal.

elements_skippedinteger required

Number of elements skipped so far. Final once scan_status is terminal. Includes elements filtered out before listing (e.g. unsupported file types), which are not counted in elements_total.

elements_failedinteger required

Number of elements that failed to scan so far. Final once scan_status is terminal.

listing_finishedboolean required

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

data_downloaded_bytesinteger nullable required

Amount of data downloaded so far, in bytes. null for sources that do not track byte counters, which is distinct from a real 0.

data_scanned_bytesinteger nullable required

Amount of data scanned so far, in bytes. null for sources that do not track byte counters, which is distinct from a real 0.

started_atstring date-time nullable required

Date and time the scan started. null while the scan is still queued.

ended_atstring date-time nullable required

Date and time the scan ended. null while it is running.

duration_secondsinteger nullable required

Duration of the scan, in seconds, from the audit summary. null until report_status is done.

pending_secondsinteger nullable required

Time the scan spent pending before it started, in seconds, from the audit summary. null until report_status is done.

outcome_by_reasonobject nullable required

Element outcome counts broken down by reason, from the audit summary, under the skipped and failed categories. null until report_status is done.

elements_by_typeobject required

Per-element-type breakdown of the counts above, for sources that track more than one kind of element.

Only populated for VCS repository scans, where it reports commit, branch and patch counters; an empty object otherwise. Note patch carries skip counters only.

Example response

{
  "scan_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "source": {
    "id": 6531,
    "visibility": "private",
    "display_name": "GitGuardian/gg-shield",
    "type": "gh_repository",
    "size": 10485760
  },
  "report_status": "in_progress",
  "scan_status": "running",
  "scan_status_reason": "DMCA takedown",
  "elements_total": 512,
  "elements_scanned": 128,
  "elements_skipped": 3,
  "data_downloaded_bytes": 10485760,
  "data_scanned_bytes": 10485760,
  "started_at": "2021-05-20T12:40:55.662949Z",
  "ended_at": "2021-05-20T12:45:12.662949Z",
  "duration_seconds": 257,
  "pending_seconds": 4,
  "outcome_by_reason": {
    "skipped": {
      "binary_file": 2,
      "too_large": 1
    },
    "failed": {
      "file_not_downloadable": 3,
      "empty_content": 1
    }
  },
  "elements_by_type": {
    "commit": {
      "scanned": 1487,
      "skipped": 3
    },
    "branch": {
      "scanned": 4
    },
    "patch": {
      "skipped": 7,
      "in_skipped_commits": 51
    }
  }
}

Changes

Changed in 1 of the 25 revisions of this API.1