space.fs.list()

List the files and folders in a bucket or a folder, one level or everything below it, a page at a time.

Lists what is in a bucket or a folder, in key order. By default it lists one level, with each folder below as one entry. With recursive: true, it lists every file below the path instead.

space.fs.list(
  path: string,
  options?: {
    recursive?: boolean
    pageSize?: number
    signal?: AbortSignal
    timeoutMs?: number
  }
): Paged<Entry>

Parameters

pathstringRequired: A bucket, such as invoices, or a folder in it, such as invoices/2026. A trailing / makes no difference.
The bucket is 3 to 63 lowercase letters, digits, and single hyphens, starting and ending with a letter or digit.
The folder follows the rules for keys: at most 1,024 bytes, no //, no folder named . or .., and no control characters.
options.recursiveboolean: true to list every file below the path, with no folder entries. false by default: one level, with each folder as one entry.
options.pageSizenumber: How many entries each page holds, a whole number from 1 to 1,000. 1,000 when you leave it out.
options.signalAbortSignal: Cancels each page’s request when it aborts. The page then rejects with aborted.
options.timeoutMsnumber: The longest each request may take, in milliseconds. The client’s timeoutMs when you leave it out, 30,000 by default.

Returns

A Paged<Entry>, straight away and without a promise. Nothing is sent until you read from it, one page at a time. Each Entry is a file or a folder, told apart by its type.

Way to read	What it does
`for await (const entry of paged)`	Goes through every entry, loading the next page as it needs it
`await paged.page(cursor?)`	Loads one page, `{ items, nextCursor }`. Pass `nextCursor` to get the next page. It is `null` on the last page
`await paged.all()`	Loads every page and resolves to one array of entries

Errors

Reading from the list rejects with a SpaceError: the loop, page(), or all(). list() itself never throws, and when an argument is wrong, nothing is sent.

Code	When
`validation_failed`	The path or an option is wrong. `issues` names each field, such as `path.prefix`
`not_found`	The bucket does not exist
`invalid_request`	The cursor passed to `page()` is not one a list gave
`forbidden`	The API key may not view files

Every call can also fail with the codes listed on SpaceError, such as timeout and network_error.

Example

list-invoices.ts

import { space } from "digitospace"

for await (const entry of space.fs.list("invoices/2026")) {
  if (entry.type === "folder") {
    console.log(`Folder ${entry.prefix}`)
  } else {
    console.log(`${entry.key}, ${entry.size} bytes`)
  }
}

Show one page at a time, such as in a table with a “Next” button:

page-of-files.ts

import { space } from "digitospace"

const files = space.fs.list("invoices", { recursive: true, pageSize: 50 })

const first = await files.page()
console.log(first.items.length)

if (first.nextCursor) {
  const second = await files.page(first.nextCursor)
  console.log(second.items.length)
}

Last updated 30 September 2026