Skip to content

List storage sweeps

GET
/admin/storage/sweeps

Returns recorded storage-integrity sweep runs, newest first.

You need system.storage.read or system.admin for the whole install; a permission held only for a team doesn’t count. Without one you get 403, and signed-out callers get 401.

Set kind to match one kind exactly (case-sensitive), or leave it out for both. An empty or unknown string normally matches no rows. Results are ordered by started_at, and ties have no fixed order. Page with limit and offset; there’s no total count or cursor. An offset with no runs left returns items: [].

Each row’s status and counters are stored progress, not a live check on the worker. running also covers queued work, and can stay set after a checkpoint or scheduling error. The job system can retry a failed run. Retries can add duplicate findings and count the same storage pair again. The response doesn’t prove every byte is healthy, and a zero findings count doesn’t rule out findings recorded by a batch that never saved its progress.

Reads go straight to the database. As runs are created and updated, offset pages can shift or repeat rows.

kind
string

Exact sweep kind: orphan_scan or checksum_verify. Leave it out for both; an empty or unknown string normally matches nothing.

limit
integer
default: 50 >= 1 <= 200

Requested page size, from 1 to 200. Defaults to 50.

offset
integer
0

Number of matching runs to skip, 0 by default. Use a non-negative value. The list is not a stable snapshot.

The requested page of run records, newest first. No total count is returned.

An offset page of recorded sweep runs, with no total count or next-page token.

object
items
required

Run records ordered by started_at, newest first. Ties have no fixed order; an empty page is [].

Array<object>

Stored progress of one storage-integrity sweep. Status and counters need not reflect current worker activity or the number of finding rows already written.

object
id
required

UUID of the sweep run, not a job ID. A trigger response may return another recent run of the requested kind.

string format: uuid
kind
required

Recorded sweep kind: orphan_scan or checksum_verify.

string
Example
orphan_scan
status
required

The last stored run label. running can mean queued or stalled work, failed can come before a retry, and completed doesn’t certify that all bytes are healthy.

string
Allowed values: running completed failed
objects_scanned
required

Cumulative number of object-and-variant entries added by saved batch checkpoints, not a count of distinct objects. Retries can count an entry again, and work before a failed checkpoint isn’t included.

integer format: int64
findings_count
required

Cumulative findings added by saved batch checkpoints. Findings are inserted separately, so this can differ from the number of stored rows or their filtered list total.

integer format: int64
started_at

When the run row was created, before the first job was queued. Left out in the minimal trigger fallback.

string format: date-time
nullable
finished_at

Last written by a completed or failed status update; left out until one is recorded. Setting it doesn’t stop further job retries.

string format: date-time
nullable
error

Stored scan error, if any; left out when none is stored. Checkpoint or scheduling errors can fail a job without setting this field.

string
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed