Skip to main content
Many AWS APIs return a limited number of results per response and include a continuation token when more results are available. In v2 of the SDK you had to check for that token and make follow-up requests manually. In v3, each paginated operation has a corresponding paginator function that handles all of that for you.

​
How paginators work

Paginators are async generator functions. When called, they return an async iterable. Each iteration yields one page of results. Internally, the paginator makes the next request using the continuation token from the previous page, stopping when the service signals no more results remain. Use them with a for await...of loop: 
for await (const page of paginator) {
  // process one page of results
}

​
Import pattern

Paginator functions are exported from the same service package as the client and commands. The function name is always paginate followed by the operation name: 
const {
  DynamoDBClient,
  paginateListTables,
} = require("@aws-sdk/client-dynamodb");

​
PaginatorConfig

Every paginator accepts a PaginatorConfig object as its first argument:
​
client
ServiceClient
required
An instantiated service client. The paginator uses this to make requests.
​
pageSize
number
The number of items to request per page. Passed as the Limit (or equivalent) parameter to the underlying operation. The service may return fewer results than requested.
​
startingToken
string
Resume pagination from a specific point. Pass a token previously returned in a page’s NextToken (or equivalent) field.

​
Full example

const {
  DynamoDBClient,
  paginateListTables,
} = require("@aws-sdk/client-dynamodb");

const paginatorConfig = {
  client: new DynamoDBClient({}),
  pageSize: 25,
};
const commandParams = {};
const paginator = paginateListTables(paginatorConfig, commandParams);

const tableNames = [];
for await (const page of paginator) {
  // page contains a single paginated output.
  tableNames.push(...page.TableNames);
}
The second argument to the paginator function is the command input object—the same parameters you would pass to the command constructor directly (for example, ExclusiveStartTableName for ListTablesCommand).

​
Simplified syntax

You can inline the config object for a more concise form: 
const client = new DynamoDBClient({});

const tableNames = [];
for await (const page of paginateListTables({ client }, {})) {
  // page contains a single paginated output.
  tableNames.push(...page.TableNames);
}

​
Runtime requirements

Paginators use the Async Iteration protocol introduced in ES2018. They are supported in:
  • Node.js 10.x and later
  • Chrome 63+, Firefox 57+, Safari 11.1+, Edge 79+
If you use TypeScript and need to compile to an older JavaScript target (ES2017 or earlier), enable "downlevelIteration": true in your tsconfig.json. TypeScript v2.3+ can compile async iterators to older targets.

​
Early exit

Because paginators are lazy generators, you can break out of the loop early without fetching unnecessary pages: 
for await (const page of paginateListTables({ client }, {})) {
  tableNames.push(...page.TableNames);
  if (tableNames.length >= 100) {
    break; // stops fetching further pages
  }
}
The paginator only requests the next page when the current iteration of the loop completes. No extra HTTP requests are made for pages you never consume.

Build docs developers (and LLMs) love

Get started for freeTalk to us