Stats & Folder Summaries

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

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

Auth: API key required on all three. A dashboard session cookie also works.

Folder summaries

GET /storage/folder-summaries

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 leaves this data out for the same reason.

Param	Type	Required	Description
`paths`	string	yes	Comma-separated folder paths, relative to the storage root. Maximum 200 per request.

An empty or missing paths returns an empty summaries object rather than an error.

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

summaries is keyed by the folder path you asked for. Each summary object holds:

itemCount, number: items counted in the folder, up to the scan ceiling
truncated, boolean: true when the folder holds more items than the scan looked at, so itemCount is a floor rather than an exact total. Render it as “99+” rather than as a count
previewItems, 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

Storage stats

GET /storage/stats

Aggregate size and file count for stored originals, and for cached transformation variants.

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

Field	Type	Description
`storage`	object	Stored originals: `size` in bytes and `fileCount`
`cache`	object	Cached transformation variants. On a cloud backend this is one number for both the local disk cache and the cache stored in the bucket
`updatedAt`	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. Recalculate to reconcile. Status codes: 200 success · 500 storage backend failed

Recalculate stats

POST /storage/stats/recalculate

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

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

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

Storage stats

Recalculate stats

List Storage

List Folders

​Folder summaries

​Storage stats

​Recalculate stats

​Related

List Storage

List Folders

Folder summaries

Storage stats

Recalculate stats

Related