Skip to content

Get storage usage

GET
/admin/storage/usage

Returns storage counts and recorded byte sizes for the whole install.

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.

These are database totals, not a disk or bucket inventory. object_count counts distinct hashes in storage_variants, and every byte total sums that table’s recorded size_bytes. Each registered object-and-variant pair counts once, however many assets use it. Original bytes are already included, so adding storage_objects.size_bytes would count them twice.

by_content_type groups variant rows by recorded content type. by_backend counts storage_objects rows by recorded backend name, so it needn’t add up to object_count: an object can be in that registry without any variant row.

The endpoint doesn’t check that recorded bytes exist, count unregistered files, measure filesystem overhead or count backup and replica copies. It includes registered data whatever the asset’s visibility and whether it’s waiting for cleanup. There’s no pagination and no handler cache. The totals and the two breakdowns are separate database reads, so concurrent writes can make them disagree.

With no variant rows, the headline counts and byte totals are zero and by_content_type is empty. by_backend can still contain positive counts for object-registry rows.

Counts, recorded byte totals and breakdowns by content type and backend, read from the database.

A database rollup of registered storage. Its counts and recorded byte sizes don’t show current backend occupancy or integrity.

object
object_count
required

Distinct object hashes represented in storage_variants, not the number of assets or all storage_objects rows.

integer format: int64
variant_count
required

Number of registered object-and-variant rows, including original.

integer format: int64
total_bytes
required

Sum of storage_variants.size_bytes, originals and derivatives included. Each registered pair counts once; this isn’t measured physical disk usage.

integer format: int64
original_bytes
required

Sum of recorded sizes for rows whose key is exactly original.

integer format: int64
derivative_bytes
required

Sum of recorded sizes for every key other than original.

integer format: int64
by_content_type
required

Variant rows grouped by recorded content type, largest byte total first. Empty when no variant rows exist; ties have no fixed order.

Array<object>

Recorded variant counts and bytes for one content-type string.

object
content_type
required

Content type recorded on the variant rows, not freshly detected from the backend bytes.

string
Example
image/png
variant_count
required

Number of registered variant rows with this content type.

integer format: int64
total_bytes
required

Sum of their recorded sizes, including original rows in this bucket.

integer format: int64
by_backend
required

Object-registry rows grouped by recorded backend name, largest count first. These counts come from storage_objects, not the variant rows used for the headline count, and are read separately.

Array<object>

Count of object-registry rows under one recorded backend name. This is not a live backend inventory.

object
backend
required

Backend name stored on the object-registry rows, such as fs or s3.

string
Example
fs
object_count
required

Number of storage_objects rows with this backend name. Rows without registered variants are still included.

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