Pagination

Objective

Read this guide before writing a loop over any describe action. The most common integration bug against this API is stopping on an empty page.

Requirements

• None

Instructions

Which actions paginate

Only the actions whose Amazon EC2 model declares MaxResults and NextToken. DescribeInstances, DescribeVolumes, DescribeSnapshots and DescribeImages paginate. DescribeRegions and DescribeAvailabilityZones do not, and never return a token.

This is not a stylistic decision. The SDKs validate parameters against their own model before sending, and their paginators only exist for actions the model marks as paginated. A token returned by an action AWS models as unpaginated is silently discarded by the client, and the caller sees a truncated list with no error at all.

Parameters

Parameter	Type	Notes
MaxResults	integer	Items per page. PROPOSED: 5 to 1000, default 1000
NextToken	string	From a previous response

MaxResults cannot be combined with an explicit list of resource ids. That combination returns InvalidParameterCombination.

The token

NextToken is opaque. Do not parse it, construct it, or store it beyond the sequence it belongs to.

A response that omits NextToken is the last page. That is the only signal that a listing has ended.

A page may contain fewer items than MaxResults, or none at all, and still carry a NextToken. This happens whenever filters remove every item from a page, and it is normal. A loop that stops on an empty page silently misses results.

token = None
while True:
    kwargs = {"MaxResults": 1000}
    if token:
        kwargs["NextToken"] = token
    page = ec2.describe_instances(**kwargs)
    handle(page["Reservations"])
    token = page.get("NextToken")
    if not token:          # not: if not page["Reservations"]
        break

PROPOSED: a token is valid for 24 hours, after which InvalidPaginationToken.

Filters

Filters are applied per page, not before pagination. This matches Amazon EC2 and is why an empty page with a token occurs.

Ordering and consistency

PROPOSED: results are ordered by creation time, oldest first, stable across pages.

A listing is not a snapshot. Items created during a pagination sequence may or may not appear. Items deleted during one may still appear, and a later read of one may return .NotFound. Reconcile after the listing completes rather than assuming it gave you a consistent view.

Go further

• Making requests
• Actions