DynamoDB Pagination: LastEvaluatedKey and Paginators

DynamoDB paginates Query and Scan results with a continuation key. Pass the response's LastEvaluatedKey unchanged as the next request's ExclusiveStartKey, and stop when that key is absent or empty. Each service request evaluates at most 1 MB of data, or the requested Limit of items, before applying filters; an empty result page can therefore still require another request.

LastEvaluatedKey and ExclusiveStartKey

LastEvaluatedKey describes the item where DynamoDB stopped evaluating the current page. It is not necessarily the last item returned to your application, because a filter can remove that item. ExclusiveStartKey tells the next request to resume after that position.

Keep the table, index, key condition, filter and direction unchanged while following a cursor. Use the entire returned key map, including index and base-table key attributes when present. Reconstructing a cursor from only a sort key can produce an invalid starting key or skip results.

A nonempty continuation key means another request is needed to discover whether results remain. It does not guarantee that request will return a matching item. The AWS pagination documentation explicitly describes this distinction.

Do not mix service keys with SDK or CLI tokens. The separate PartiQL API also has a NextToken, but it belongs to that API, not to Query or Scan.

Manual Query pagination with SDK v3

This example uses invoices with String partition key accountId and String sort key createdAt. Dates are consistently formatted UTC timestamps. Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb, configure credentials and a Region, and run it as an ES module.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))
const input = {
  TableName: "invoices",
  KeyConditionExpression: "#account = :account AND #created >= :since",
  FilterExpression: "#status = :status",
  ExpressionAttributeNames: {
    "#account": "accountId", "#created": "createdAt", "#status": "status",
  },
  ExpressionAttributeValues: {
    ":account": "account-123", ":since": "2026-10-01T00:00:00Z", ":status": "OPEN",
  },
  Limit: 100,
  ReturnConsumedCapacity: "TOTAL",
}

let startKey
let returned = 0
let evaluated = 0
let consumed = 0

do {
  const page = await client.send(new QueryCommand({
    ...input,
    ...(startKey ? { ExclusiveStartKey: startKey } : {}),
  }))

  for (const invoice of page.Items ?? []) console.log(invoice)
  returned += page.Count ?? 0
  evaluated += page.ScannedCount ?? 0
  consumed += page.ConsumedCapacity?.CapacityUnits ?? 0
  startKey = page.LastEvaluatedKey
} while (startKey && Object.keys(startKey).length > 0)

console.log({ returned, evaluated, consumed })
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))
const input = {
  TableName: "invoices",
  KeyConditionExpression: "#account = :account AND #created >= :since",
  FilterExpression: "#status = :status",
  ExpressionAttributeNames: {
    "#account": "accountId", "#created": "createdAt", "#status": "status",
  },
  ExpressionAttributeValues: {
    ":account": "account-123", ":since": "2026-10-01T00:00:00Z", ":status": "OPEN",
  },
  Limit: 100,
  ReturnConsumedCapacity: "TOTAL",
}

let startKey
let returned = 0
let evaluated = 0
let consumed = 0

do {
  const page = await client.send(new QueryCommand({
    ...input,
    ...(startKey ? { ExclusiveStartKey: startKey } : {}),
  }))

  for (const invoice of page.Items ?? []) console.log(invoice)
  returned += page.Count ?? 0
  evaluated += page.ScannedCount ?? 0
  consumed += page.ConsumedCapacity?.CapacityUnits ?? 0
  startKey = page.LastEvaluatedKey
} while (startKey && Object.keys(startKey).length > 0)

console.log({ returned, evaluated, consumed })

The loop processes one page at a time, which keeps memory bounded. If a small result set is needed as an array, append each page's items to an accumulator instead. For a reconciliation job, persist output and a checkpoint only after processing succeeds, and make replaying a page safe.

Do not use Items.length || LastEvaluatedKey as the loop condition. A final nonempty page without a key would run the loop again with no starting position, restarting the query. Do not use Items.length alone either: an empty filtered page can precede more matches.

SDK v3 paginateQuery and paginateScan

The document client provides async iterators that handle service continuation keys. Both paginator functions below come from @aws-sdk/lib-dynamodb, so inputs and results use ordinary JavaScript values. The AWS SDK v3 examples use this interface.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, paginateQuery, paginateScan } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))

for await (const page of paginateQuery({ client, pageSize: 100 }, {
  TableName: "invoices",
  KeyConditionExpression: "#account = :account",
  ExpressionAttributeNames: { "#account": "accountId" },
  ExpressionAttributeValues: { ":account": "account-123" },
})) {
  for (const invoice of page.Items ?? []) console.log(invoice)
}

// This is a separate whole-table job, not part of the query above.
for await (const page of paginateScan({ client, pageSize: 100 }, {
  TableName: "invoices",
})) {
  console.log(page.Items ?? [])
}
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient, paginateQuery, paginateScan } from "@aws-sdk/lib-dynamodb"

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}))

for await (const page of paginateQuery({ client, pageSize: 100 }, {
  TableName: "invoices",
  KeyConditionExpression: "#account = :account",
  ExpressionAttributeNames: { "#account": "accountId" },
  ExpressionAttributeValues: { ":account": "account-123" },
})) {
  for (const invoice of page.Items ?? []) console.log(invoice)
}

// This is a separate whole-table job, not part of the query above.
for await (const page of paginateScan({ client, pageSize: 100 }, {
  TableName: "invoices",
})) {
  console.log(page.Items ?? [])
}

pageSize controls the evaluated-item limit per service call. It does not guarantee that many returned items and does not limit total work. Fully consuming paginateScan still reads the table; breaking out of the iterator stops requesting later pages. The Scan guide covers pacing and parallel workers.

Python boto3 paginators

Use the low-level boto3 client to obtain a Query or Scan paginator. Unlike the JavaScript document client, this interface uses DynamoDB JSON with explicit type descriptors.

import boto3

client = boto3.client("dynamodb")
paginator = client.get_paginator("query")

for page in paginator.paginate(
    TableName="invoices",
    KeyConditionExpression="#account = :account",
    ExpressionAttributeNames={"#account": "accountId"},
    ExpressionAttributeValues={":account": {"S": "account-123"}},
    PaginationConfig={"PageSize": 100},
):
    for invoice in page.get("Items", []):
        print(invoice)
import boto3

client = boto3.client("dynamodb")
paginator = client.get_paginator("query")

for page in paginator.paginate(
    TableName="invoices",
    KeyConditionExpression="#account = :account",
    ExpressionAttributeNames={"#account": "accountId"},
    ExpressionAttributeValues={":account": {"S": "account-123"}},
    PaginationConfig={"PageSize": 100},
):
    for invoice in page.get("Items", []):
        print(invoice)

For a whole-table scan, use client.get_paginator("scan") and remove the query-only key condition and its placeholders. PaginationConfig.PageSize controls individual service requests; MaxItems limits the paginator's returned items. If you use MaxItems, resume with the paginator's token rather than a raw service key. For a deliberately small bounded result:

request = {
    "TableName": "invoices",
    "KeyConditionExpression": "#account = :account",
    "ExpressionAttributeNames": {"#account": "accountId"},
    "ExpressionAttributeValues": {":account": {"S": "account-123"}},
}

result = paginator.paginate(
    **request,
    PaginationConfig={"PageSize": 25, "MaxItems": 25},
).build_full_result()
print(result.get("Items", []))

token = result.get("NextToken")
if token:
    next_result = paginator.paginate(
        **request,
        PaginationConfig={"PageSize": 25, "MaxItems": 25, "StartingToken": token},
    ).build_full_result()
    print(next_result.get("Items", []))
request = {
    "TableName": "invoices",
    "KeyConditionExpression": "#account = :account",
    "ExpressionAttributeNames": {"#account": "accountId"},
    "ExpressionAttributeValues": {":account": {"S": "account-123"}},
}

result = paginator.paginate(
    **request,
    PaginationConfig={"PageSize": 25, "MaxItems": 25},
).build_full_result()
print(result.get("Items", []))

token = result.get("NextToken")
if token:
    next_result = paginator.paginate(
        **request,
        PaginationConfig={"PageSize": 25, "MaxItems": 25, "StartingToken": token},
    ).build_full_result()
    print(next_result.get("Items", []))

build_full_result() collects the selected results in memory. Prefer the page iterator for large jobs. The boto3 Query paginator reference defines these configuration fields.

AWS CLI v2 auto-pagination

The CLI automatically follows Query and Scan pages unless you disable pagination. --no-cli-pager only disables the terminal display pager; it does not disable network pagination.

aws dynamodb query \
  --table-name invoices \
  --key-condition-expression '#account = :account' \
  --expression-attribute-names '{"#account":"accountId"}' \
  --expression-attribute-values '{":account":{"S":"account-123"}}' \
  --page-size 25 \
  --max-items 25 \
  --output json \
  --no-cli-pager
aws dynamodb query \
  --table-name invoices \
  --key-condition-expression '#account = :account' \
  --expression-attribute-names '{"#account":"accountId"}' \
  --expression-attribute-values '{":account":{"S":"account-123"}}' \
  --page-size 25 \
  --max-items 25 \
  --output json \
  --no-cli-pager

If the result includes NextToken, copy it unchanged into the next invocation's --starting-token while keeping the other options the same. For example, after assigning that output token to a shell variable named TOKEN, append --starting-token "$TOKEN" to the command.

For manual service pagination, combine --no-paginate with --limit, save LastEvaluatedKey as JSON, and pass that map with --exclusive-start-key file://last-key.json. Do not feed a CLI NextToken to --exclusive-start-key. When resuming CLI pagination, keeping --page-size and --max-items equal avoids the client-side truncation mismatch described in the AWS CLI pagination guide.

Filters and application page sizes

A UI asking for 20 visible invoices may need several service calls if a FilterExpression removes candidates. Decide whether to return a short page with a next cursor, or keep reading until you collect enough results. Put a maximum on requests, evaluated items or elapsed time so a sparse match cannot create an unbounded API request.

If you collect more items than the UI page can display, retain the overflow in cursor state or choose a continuation position that does not skip it. Returning the service's end-of-page key after discarding undisplayed matches loses those matches. An easier contract returns complete service pages, with a variable number of visible items.

Smaller pages smooth resource usage and let callers stop early. Reading all pages still incurs the full read work; splitting the same job into more calls is not itself a cost reduction. Choose the correct key access pattern first, as described in Query vs Scan.

Encode a cursor for an HTTP API

Keep DynamoDB's key structure behind an opaque application cursor. For a schema with String keys, base64url encoding is a convenient transport format:

const encodeCursor = (key) => key && Object.keys(key).length > 0
  ? Buffer.from(JSON.stringify({ version: 1, key }), "utf8").toString("base64url")
  : null

const decodeCursor = (token) => {
  const payload = JSON.parse(Buffer.from(token, "base64url").toString("utf8"))
  if (payload.version !== 1 || typeof payload.key?.accountId !== "string" ||
      typeof payload.key?.createdAt !== "string") {
    throw new Error("Invalid cursor")
  }
  return payload.key
}
const encodeCursor = (key) => key && Object.keys(key).length > 0
  ? Buffer.from(JSON.stringify({ version: 1, key }), "utf8").toString("base64url")
  : null

const decodeCursor = (token) => {
  const payload = JSON.parse(Buffer.from(token, "base64url").toString("utf8"))
  if (payload.version !== 1 || typeof payload.key?.accountId !== "string" ||
      typeof payload.key?.createdAt !== "string") {
    throw new Error("Invalid cursor")
  }
  return payload.key
}

This demonstrates encoding, not a complete public API security boundary. Base64 is reversible and provides no tamper protection. Reject oversized or malformed input, validate exact key fields and types, bind the cursor to the authenticated account and query parameters, and sign it or keep cursor state server-side. Always derive authorization constraints from the session, not from the cursor. If the cursor carries sensitive values, encryption or a server-side reference also prevents disclosure.

Use a serializer that preserves binary keys and high-precision numeric keys if your schema includes them. A plain JSON round trip is sufficient for the String-key example above, but is not a universal DynamoDB key codec.

Page numbers, offsets, ordering and totals

DynamoDB Query and Scan do not support an SQL-style offset. To reach page 10, you must traverse preceding pages or reuse previously saved starting cursors. Infinite scroll and next-page links fit this model. For a previous-page button, retain the starting cursor for each displayed page; the cursor is not inherently bidirectional.

Query returns sort-key order, and ScanIndexForward: false reverses it. A Scan has no useful application sort order. Neither a series of queries nor a strongly consistent scan gives a frozen snapshot across the entire traversal. Inserts and updates can change what later pages contain, so define whether a UI shows live data or needs an independently materialized snapshot.

You can obtain an exact matching count by paginating Select: "COUNT" and summing each response's Count, but this still reads the candidates. A maintained counter is an alternative for frequently displayed totals. Avoid promising a stable page count for a live, changing dataset.

For invoice updates and reconciliation, process every required page even if the initial dataset seems small. The service's byte boundary still applies when your application does not expose page navigation. Large tables are distributed internally, but the application continues through the same key-based API. DynamoDB Streams use shard iterators and GetRecords, a different protocol covered in the Streams guide.