Skip to content

List storage sweep findings

GET
/admin/storage/sweeps/{id}/findings

Returns the findings recorded for one storage sweep.

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.

The path id is a sweep-run UUID. The handler doesn’t check that the run exists: a well-formed unknown ID returns 200 with items: [] and total: 0, not the declared 404.

Filter with finding for one exact, case-sensitive finding type, or leave it out for all types; empty or unknown values normally match nothing. Results are newest first by detected_at, then by finding UUID ascending. Resolved and unresolved rows are both included, and there’s no resolved-state filter or resolve action here.

total counts every matching row for the run, ignoring paging. It’s read separately from the page, so new findings or run deletion can make the two disagree, and an offset past the end can return an empty list with a positive total. Use limit and a non-negative offset; changing data can make offset pages skip or repeat rows.

Findings record what a scan observed. Retries can duplicate them, they can outlive the storage bytes they refer to, and they can stay after the problem is fixed. Recheck the bytes and their current references before acting. This endpoint doesn’t look at the backend again.

id
required
string format: uuid

UUID of the sweep run whose recorded findings to list. A well-formed ID with no findings returns an empty page, whether or not the run exists.

finding
string

Exact finding type to include: missing_object, orphan_object, checksum_mismatch or size_mismatch. Leave it out for all types; an empty or unknown string normally matches none.

limit
integer
default: 50 >= 1 <= 200

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

offset
integer
0

Number of matching findings to skip, 0 by default. Use a non-negative value. New findings can shift offset pages.

A page of recorded findings and a separately read count under the same filters. An unknown run ID gets this response too, with an empty list and a zero total.

An offset page of findings and a separately read matching count.

object
items
required

Recorded findings ordered by detected_at descending, then UUID ascending. Empty when the requested page has no rows.

Array<object>

One recorded scan observation, not a current integrity verdict or a go-ahead to act. Retries can create several findings for the same pair, and this API doesn’t resolve them automatically.

object
id
required

UUID of this finding row.

string format: uuid
finding
required

Observed classification. missing_object: backend bytes weren’t found. orphan_object: no matching variant-registry row was found. checksum_mismatch: an original’s hash differs. size_mismatch: the bytes differ from a positive recorded size. One verification attempt records at most one of these for a pair.

string
Allowed values: missing_object orphan_object checksum_mismatch size_mismatch
object_hash
required

Parent object hash associated with the finding. It identifies the original content, not a derivative checksum or an asset UUID.

string
variant_key
required

Full variant key that was examined, such as original or turntable/0028.png.

string
detail
required

Diagnostic details recorded by the scan, such as sizes, backend name or abbreviated hashes. They describe scan-time observations, not a fresh check.

string
detected_at

Timestamp assigned when the finding row was inserted. Left out only if no timestamp is available.

string format: date-time
nullable
resolved_at

Resolution timestamp, if one is stored. The current sweep endpoints neither set it nor filter out resolved rows, so it’s normally left out.

string format: date-time
nullable
total
required

Number of finding rows for the run and filter, ignoring pagination and resolution state. It’s read separately from items. The filtered row count can differ from the run record’s separately checkpointed findings_count.

integer format: int64

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

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed