Stats & Folder Summaries

Three endpoints that answer “how much is in there” without listing everything: aggregate totals for the whole bucket, and bounded per-folder summaries for the folders a client is currently showing.

Folder summaries

GET /storage/folder-summaries

Auth: API key required. A dashboard session cookie also works. Returns an item count and up to four preview items per folder. Call it only for the folders you are actually rendering, such as the rows currently on screen, so a level with many subfolders does not pay for every summary up front. List Storage deliberately leaves this data out for the same reason.

Query parameters

string

required

Comma-separated folder paths, relative to the storage root. Maximum 200 per request. An empty or missing value returns an empty summaries object rather than an error.photos,videos · photos/2026,archive

Response

{
  "summaries": {
    "photos": {
      "itemCount": 42,
      "truncated": false,
      "previewItems": [
        { "path": "photos/portrait.jpg", "type": "image" },
        { "path": "photos/clip.mp4", "type": "video" }
      ]
    }
  }
}

object

Keyed by the folder path you asked for.

Show Summary object

number

Items counted in the folder, up to the scan ceiling.

boolean

true when the folder holds more items than the scan looked at, which means itemCount is a floor rather than an exact total. Render it as “99+” rather than as a count.

array

Up to four items for a folder thumbnail, each { path, type } where type is image or video. Files that are neither are skipped.

Status codes: 200 success · 400 more than 200 paths, or a path that escapes the storage root · 500 storage backend failed

Example

curl "http://localhost:3000/storage/folder-summaries?paths=photos,videos" \
  -H "Authorization: Bearer <api_key>"

Storage stats

GET /storage/stats

Auth: API key required. A dashboard session cookie also works. Aggregate size and file count for stored originals, and for cached transformation variants.

Response

{
  "storage": { "size": 5242880, "fileCount": 128 },
  "cache": { "size": 1048576, "fileCount": 64 },
  "updatedAt": "2026-03-15T10:30:00.000Z"
}

object

Stored originals: size in bytes and fileCount.

object

Cached transformation variants. On a cloud backend this combines the local disk cache with the cache stored in the bucket, so it is one number for both.

string

ISO 8601 timestamp of the counters these figures came from. On local storage the tree is walked per request, so this is always now.

On a cloud backend the figures come from incremental counters rather than a live bucket listing, which is what keeps this endpoint cheap. They can drift if the bucket is changed outside Openinary. Use the recalculate endpoint below to reconcile.

Status codes: 200 success · 500 storage backend failed

Recalculate stats

POST /storage/stats/recalculate

Auth: API key required. A dashboard session cookie also works. Recomputes the aggregates from a full bucket listing and returns the same shape as GET /storage/stats. Use it when the counters have drifted, typically after objects were added or removed outside Openinary.

This lists the entire bucket. On a large bucket it is slow and it costs list operations at your storage provider. Run it when you have reason to think the counters are wrong, not on a schedule.

Status codes: 200 success · 500 storage backend failed

Example

curl -X POST http://localhost:3000/storage/stats/recalculate \
  -H "Authorization: Bearer <api_key>"

List Storage

Browse folders and files one level at a time.

List Folders

Every folder path, for building a folder picker.

Overview

Media

Files

Storage

Cache

Video Processing

API Keys

System

Folder summaries

Query parameters

Response

Example

Storage stats

Response

Recalculate stats

Example

List Storage

List Folders

​Folder summaries

​Query parameters

​Response

​Example

​Storage stats

​Response

​Recalculate stats

​Example

​Related

List Storage

List Folders

Folder summaries

Query parameters

Response

Example

Storage stats

Response

Recalculate stats

Example

Related