Listing & pagination

Listing walks the keys in a bucket. This page covers both clients, the delimiter and common-prefix model, and full paging loops.

• The native client has listObjects with prefix/delimiter semantics and an iterator that follows continuation tokens.
• The S3 client has two forms: ListObjectsV2 (the token-paged default) and ListObjects (the older marker-paged v1), plus paginators that follow the tokens for you.

For the operation matrix, see the native data-plane reference and the S3 operations reference.

One pageCopy Anchor Link

A single listing call returns one page. prefix filters by key prefix; maxKeys caps the page (the server caps it at 1000); the page reports isTruncated and a nextContinuationToken when more remains.

const page = await native.listObjects("reports", { prefix: "q1/", maxKeys: 100 });
for (const o of page.objects) console.log(o.key, o.size);
console.log(page.isTruncated, page.nextContinuationToken);

const page = await s3.listObjectsV2("reports", { prefix: "q1/", maxKeys: 100 });
for (const o of page.objects) console.log(o.key, o.size, o.etag);
console.log(page.isTruncated, page.nextContinuationToken);

Listing optionsCopy Anchor Link

startAfter begins the listing after a given key (a one-shot starting point, not a resume token). continuationToken resumes a previously truncated listing.

Delimiters and common prefixesCopy Anchor Link

A delimiter (almost always "/") makes the listing behave like a directory walk. Keys that share a prefix up to the next delimiter are collapsed into a single entry in commonPrefixes; only keys with no further delimiter past the prefix appear in objects.

Given these keys:

logs/2026/01/a.log
logs/2026/01/b.log
logs/2026/02/c.log
logs/index.txt

a listing with prefix: "logs/" and delimiter: "/" returns:

• objects: logs/index.txt
• commonPrefixes: logs/2026/

To descend, list again with the common prefix as the new prefix. Without a delimiter, the listing is flat: every key under the prefix comes back in objects.

const page = await native.listObjects("archive", { prefix: "logs/", delimiter: "/" });
console.log(page.commonPrefixes); // ["logs/2026/"]
for (const o of page.objects) console.log(o.key); // "logs/index.txt"

const page = await s3.listObjectsV2("archive", { prefix: "logs/", delimiter: "/" });
console.log(page.commonPrefixes); // ["logs/2026/"]
for (const o of page.objects) console.log(o.key); // "logs/index.txt"

Paging across all keysCopy Anchor Link

To walk every key, follow isTruncated with the continuation token until it clears. The native client ships an iterator that does this for you; the S3 client ships paginators per listing operation.

The native iterator (ListObjectsAll in Go, the paginateObjects async generator in Node) transparently follows continuation tokens.

for await (const page of native.paginateObjects("reports", { prefix: "q1/" })) {
  for (const o of page.objects) console.log(o.key, o.size);
}

// Node uses async iterators rather than a paginator object:
for await (const page of s3.paginateObjectsV2("reports", { prefix: "q1/" })) {
  for (const o of page.objects) console.log(o.key, o.size);
}

Paging by handCopy Anchor Link

If you would rather drive the loop yourself, follow isTruncated with the continuation token until it clears.

let token;
do {
  const page = await native.listObjects(
    "reports",
    token ? { prefix: "q1/", continuationToken: token } : { prefix: "q1/" },
  );
  for (const o of page.objects) console.log(o.key);
  token = page.isTruncated ? page.nextContinuationToken : undefined;
} while (token);

let token;
do {
  const page = await s3.listObjectsV2(
    "reports",
    token ? { prefix: "q1/", continuationToken: token } : { prefix: "q1/" },
  );
  for (const o of page.objects) console.log(o.key);
  token = page.isTruncated ? page.nextContinuationToken : undefined;
} while (token);

ListObjects v1 (marker pagination)Copy Anchor Link

The S3 client also exposes the v1 ListObjects, which pages by a marker (the last key returned) rather than an opaque token. Prefer ListObjectsV2 (or the native listing) for new code; v1 exists for parity with clients that still page by marker.

let marker;
do {
  const page = await s3.listObjects("reports", marker ? { prefix: "v1/", marker } : { prefix: "v1/" });
  for (const o of page.objects) console.log(o.key);
  marker = page.isTruncated ? page.nextMarker || page.objects.at(-1)?.key : undefined;
} while (marker);

When a delimiter collapses the truncation boundary onto a common prefix, the server may omit NextMarker. In that case resume from the last key or common prefix you saw, which is what the Node and Go paginators do for you.

Listing versions and multipart uploadsCopy Anchor Link

Versioned listings (ListObjectVersions) and in-progress multipart uploads (ListMultipartUploads, ListParts) share this prefix/delimiter/marker model. They each have a dedicated page:

• Versioning: list versions and delete markers.
• Multipart uploads: list uploads and their parts.

Next stepsCopy Anchor Link

• Upload & download: the put/get/head you are listing.
• Copying objects: duplicate keys you found in a listing.
• Deleting objects: batch-delete a listed prefix.