Skip to content

List storage variant families

GET
/admin/storage/variants

Returns registered storage variants grouped by key family.

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.

A family is the part of variant_key before its first /, or the whole key if there’s no slash. For example, turntable/0028.png belongs to turntable, while original and hires are each their own family. Originals are included, so this isn’t a derivatives-only list.

Results are ordered by total recorded bytes, largest first, and ties have no fixed order. variant_count counts rows, distinct_keys counts full keys in the family and object_count counts distinct parent hashes. One object can appear in several families, so adding up family object counts doesn’t give an install-wide distinct count.

Byte sizes come from storage_variants, not a fresh look at the backend. newest_at is the latest row creation time in the family, not the last time a variant was regenerated. The endpoint runs one uncached database query and returns every family with no pagination. With no registered variants, it returns items: [].

All registered variant families ordered by recorded byte total, largest first.

All registered variant families, without pagination.

object
items
required

Family buckets ordered by recorded byte total, largest first. Ties have no fixed order; empty when no variant rows exist.

Array<object>

Database inventory for one variant-key family, including the original family. Recorded sizes do not prove that the bytes are present.

object
family
required

The key segment before the first /, or the whole key when there is no slash.

string
Example
turntable
variant_count
required

Number of registered object-and-variant rows in this family.

integer format: int64
distinct_keys
required

Number of distinct full variant keys in this family, across all represented objects.

integer format: int64
object_count
required

Distinct parent hashes with at least one registered variant in this family. The same hash can be counted in other families.

integer format: int64
total_bytes
required

Sum of recorded variant sizes in this family.

integer format: int64
newest_at

Latest created_at among the family’s rows. Regenerating an existing variant changes updated_at, not this creation timestamp.

string format: date-time
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