---
title: "Retrieve a scan's live progress"
method: GET
path: "/v1/scans/{scan_id}/live-progress"
tags: ["Sources"]
---

# Retrieve a scan's live progress

`GET /v1/scans/{scan_id}/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.

## Path parameters

- `scan_id` string, uuid, required

## Response `200`

Scan live progress

- object — ⚠️ **Beta schema**: subject to change. Live progress of a historical scan. Poll this while a scan is running instead of the scan detail endpoint.
  - `status` 'queued' | 'in_progress' | 'completed', required — Coarse live-progress phase of the scan.
  - `audit_url` string, nullable — URL of the scan's audit summary. Only present once `status` is `completed`.
  - `elements_scanned` integer, nullable — Number of elements scanned so far. Once `status` is `completed` this is the scan's final count.
  - `elements_total` integer, 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_finished` boolean, nullable — Whether the scan has finished listing all its elements, i.e. whether `elements_total` reflects the true final count.
  - `elements_skipped` integer, nullable — Number of elements skipped so far. Once `status` is `completed` this is the scan's final count.
  - `elements_failed` integer, nullable — Number of elements that failed to scan so far. Once `status` is `completed` this is the scan's final count.
  - `data_downloaded_bytes` integer, 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_bytes` integer, 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.

## Other responses

- `400` — Invalid data
- `401` — Invalid API key
- `403` — Forbidden Call
- `404` — Scan not found
- `503` — API under maintenance

## Changes

- **2026-08-14** `0a06e9c0187a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/gitguardian/apis/gitguardian-api/changes/v1/scans/:scan_id/live-progress/get.md)

---

[API](https://skmtc.dev/gitguardian/apis/gitguardian-api.md) · [All operations](https://skmtc.dev/gitguardian/apis/gitguardian-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitguardian/gitguardian-api/revisions/93137300f743/schema)