Browse the Box

What you'll learn

Prefix filters keys by their start; Delimiter groups the rest into CommonPrefixes — the “folders”.
Each ListObjectsV2 page has up to 1,000 keys; follow NextContinuationToken until IsTruncated is false.
Listing is for browsing and batch jobs, not lookups: if you know the key, GET it directly.

Section 01

Prefix and delimiter

Prefix keeps only keys that start with that string. Delimiter (usually /) tells S3 to roll up everything after the next delimiter into a CommonPrefixes entry, so one level at a time looks like a folder listing.

A prefix is plain string matching. sprites/grass also matches sprites/grass-old/… — end it with the delimiter when you mean one folder.

Try it · Prefix explorer

14 objects in the bucket. There are no folders — only keys, and the listing groups them for you.

PrefixDelimiter /

new ListObjectsV2Command({ Bucket: "hoenn-pokedex-media", Prefix: "sprites/", Delimiter: "/" })

CommonPrefixes (4)

Contents (0)

No keys match directly.

Click a common prefix to “open” it. Compare sprites/grass with sprites/grass/: a prefix is a plain string match.

Section 02

Pages of 1,000

Keys come back in UTF-8 binary order, up to 1,000 per response (MaxKeys can lower that, never raise it). When there are more, IsTruncated is true and NextContinuationToken tells S3 where to resume.

The SDK paginator does the loop for youJavaScript

import { paginateListObjectsV2 } from "@aws-sdk/client-s3";

const keys = [];
for await (const page of paginateListObjectsV2(
  { client },
  { Bucket: "hoenn-pokedex-media", Prefix: "sprites/grass/" }
)) {
  for (const obj of page.Contents ?? []) keys.push(obj.Key);
}

Section 03

Prefixes and throughput

S3 supports at least 3,500 PUT/COPY/POST/DELETE and 5,500 GET/HEAD requests per second per partitioned prefix, and there's no limit on the number of prefixes. If traffic grows suddenly S3 may answer 503 SlowDown while it scales; the SDK retries with backoff.

You rarely need to design for this at Pokédex scale, but spreading hot data over several prefixes is the lever when you do (Quest 12).

Practice

Your turn

List every grass-type sprite. There are more than 1,000, so a single ListObjectsV2 call won't return them all. Scope the listing with a prefix and keep asking for the next page until S3 says there are no more.

Prefix: "sprites/grass/", pass ContinuationToken, and loop on NextContinuationToken.

// @ts-nocheck
import { S3Client, ListObjectsV2Command } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "ap-south-1" });
async function listGrassSprites() {
  const keys = [];
  const page = await client.send(
    new ListObjectsV2Command({
      Bucket: "hoenn-pokedex-media",
      // ⬇️ Only grass sprites, please.
      Prefix: "sprites/",
    })
  );
  for (const obj of page.Contents ?? []) keys.push(obj.Key);
  // ⬇️ This stops after the first 1,000 keys. Loop until the listing is complete.
  console.log("Found", keys.length, "sprites");
}

// @ts-nocheck
import { S3Client, ListObjectsV2Command } from "@aws-sdk/client-s3";

const client = new S3Client({ region: "ap-south-1" });

async function listGrassSprites() {
  const keys = [];

  const page = await client.send(
    new ListObjectsV2Command({
      Bucket: "hoenn-pokedex-media",
      // ⬇️ Only grass sprites, please.
      Prefix: "sprites/",
    })
  );
  for (const obj of page.Contents ?? []) keys.push(obj.Key);

  // ⬇️ This stops after the first 1,000 keys. Loop until the listing is complete.
  console.log("Found", keys.length, "sprites");
}

Ctrl/⌘ Enter to run · simulated, no AWS callsSimulated — no AWS calls

Check

Check your understanding

Quick Quiz · one question, as many tries as you need.

You call ListObjectsV2 with Prefix: "sprites/" and Delimiter: "/". Where does sprites/grass/0252-treecko.png appear?

Choose one answer.