Sign in
Sources

List scans

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

List historical scans with the same payload the scan detail endpoint returns, so a whole perimeter can be polled in one request instead of one request per scan.

Use active_or_updated_since to poll: it keeps every scan that is still running plus every scan whose payload moved since that instant, which is what a plain "not finished" filter would lose — a scan ending, or its audit summary landing minutes later, between two polls.

get/v1/scans

Query parameters

cursorstring

Pagination cursor.

per_pageinteger

Number of items to list per page.

active_or_updated_sincestring date-time
Example:2025-09-22T10:00:00Z

Keep only scans that are still running or whose payload changed at or after this instant (ISO 8601).

ordering'gg_created_at' | '-gg_created_at'

Sort the results by their field value. The default sort is ASC, DESC if the field is preceded by a '-'. Defaults to -gg_created_at.

Response

Scan list

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