list

Cursor-paginated listing with a prefix filter; each item is a StoredFile with a lazy body accessor. listAll walks every page; a delimiter returns folders.

files.list(options?)

Cursor-paginated listing with prefix filter. Each item is a StoredFile with a lazy body accessor.

const { items, cursor } = await files.list({
  prefix: "avatars/",
  limit: 100,
});

if (cursor) {
  const next = await files.list({ prefix: "avatars/", cursor });
}

Walking every page with listAll

list returns one page plus a cursor; most callers actually want “walk everything under this prefix”, which is a manual cursor loop. files.listAll(options?) is that loop as an async iterable:

for await (const file of files.listAll({ prefix: "avatars/" })) {
  console.log(file.key, file.size);
}

Each item is the same StoredFile list yields. prefix scopes the walk; limit sets the page size each underlying list fetches (not a total cap), and a cursor resumes from a prior position. Every page is a real list call, so it honors the client prefix, retries and timeouts, and fires one onAction list event per page. break out of the loop to stop early — no further pages are fetched.

listAll runs on every adapter, since it’s built on list. One list caveat carries over to the walk: the folder-based Box, OneDrive, and SharePoint adapters list one folder at a time and don’t recurse. list reads the folder that prefix points into (everything up to its last /, or the root folder when there’s no prefix), so listAll walks every page of that folder but never descends into its subfolders. Walk each subfolder with its own prefix, discovering them with delimiter: "/".

Listing folders with delimiter

Pass a delimiter to collapse keys at that boundary into common prefixes (“folders”) — the building block for a file-browser UI. With delimiter: "/", a page returns only the files directly under prefix in items, and the subfolders in prefixes (full keys including the trailing delimiter); keys nested deeper are folded into those prefixes rather than listed.

const { items, prefixes } = await files.list({
  prefix: "photos/",
  delimiter: "/",
});

// Render one level of a browser:
for (const folder of prefixes ?? []) {
  console.log("📁", folder); // "photos/2023/", "photos/2024/"
}
for (const file of items) {
  console.log("📄", file.key); // "photos/cover.jpg"
}

prefixes is omitted when no delimiter is set or none are found. The page cursor walks items and prefixes together (a folder counts as one entry against limit); hold prefix and delimiter constant across a paginated sequence, just like prefix alone.

listAll ignores delimiter — it walks the whole tree, so use list directly for the folder view.

Provider support

• Any delimiter string — the object stores with native common-prefix listing: S3 and the whole s3() family, R2, Bun’s S3, Google Cloud Storage, Firebase Storage, Azure Blob, plus the local fs, in-memory, FTP, SFTP, WebDAV, Google Drive, and Cloudinary adapters (which synthesize prefixes from the key list).
• "/" only — the folder-based providers: Vercel Blob, Netlify Blobs, Supabase, Dropbox, Box, OneDrive, SharePoint. Any other delimiter throws.
• Unsupported — adapters that can’t return common prefixes: UploadThing, Appwrite, PocketBase, Convex, and Bunny Storage. Passing a delimiter throws a FilesError before any provider call rather than silently returning a flat list — branch on adapter.supportsDelimiter to check at runtime.

Options

Both list and listAll take the same options:

Result