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.
Authorizations
Section titled “Authorizations ”Responses
Section titled “ Responses ”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
Distinct object hashes represented in storage_variants, not the number of assets or all storage_objects rows.
Number of registered object-and-variant rows, including original.
Sum of storage_variants.size_bytes, originals and derivatives included. Each registered pair counts once; this isn’t measured physical disk usage.
Sum of recorded sizes for rows whose key is exactly original.
Sum of recorded sizes for every key other than original.
Variant rows grouped by recorded content type, largest byte total first. Empty when no variant rows exist; ties have no fixed order.
Recorded variant counts and bytes for one content-type string.
object
Content type recorded on the variant rows, not freshly detected from the backend bytes.
Example
image/pngNumber of registered variant rows with this content type.
Sum of their recorded sizes, including original rows in this bucket.
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.
Count of object-registry rows under one recorded backend name. This is not a live backend inventory.
object
Backend name stored on the object-registry rows, such as fs or s3.
Example
fsNumber of storage_objects rows with this backend name. Rows without registered variants are still included.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed