---
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, while the scan is running,
element/byte counters read straight from the scan's in-memory progress
tracking.

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. Absent when `status` is `completed`.
  - `elements_total` integer, nullable — Number of elements listed so far. Provisional (still growing) until `listing_finished` is `true`. Absent when `status` is `completed`.
  - `listing_finished` boolean, nullable — Whether the scan has finished listing all its elements, i.e. whether `elements_total` reflects the true final count. Absent when `status` is `completed`.
  - `elements_skipped` integer, nullable — Number of elements skipped so far. Absent when `status` is `completed`.
  - `elements_failed` integer, nullable — Number of elements that failed to scan so far. Absent when `status` is `completed`.
  - `data_downloaded_bytes` integer, nullable — Amount of data downloaded so far, in bytes. Absent when `status` is `completed`.
  - `data_scanned_bytes` integer, nullable — Amount of data scanned so far, in bytes. Absent when `status` is `completed`.

## Other responses

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

---

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