Pagination

Objective

Read this page before writing any loop over a list operation. The most common integration bug against this platform is stopping on an empty page.

Requirements

• None

Instructions

Which operations paginate

Only those whose mirrored AWS model declares MaxResults and NextToken.

This is a constraint rather than a preference. The AWS SDKs validate parameters against their own service model before sending, and their paginators exist only for operations the model marks as paginated. Two failures follow from getting this wrong:

• Adding MaxResults to an operation AWS does not model with one means the customer’s SDK rejects the call before it is sent.
• Returning a NextToken from an operation AWS models as unpaginated means the SDK discards it silently. The caller receives a truncated list, with no error, and believes it is complete. Half the regions, half the zones, and no indication that anything is missing.

DescribeInstances, DescribeVolumes, DescribeSnapshots and DescribeImages paginate. DescribeRegions, DescribeAvailabilityZones and DescribeAccountAttributes do not, and must never return a token.

Services with no AWS counterpart paginate wherever a list can grow.

Parameters

Parameter	Type	Notes
MaxResults	integer	Items per page
NextToken	string	From a previous response

PROPOSED: MaxResults accepts 5 to 1000, defaulting to 1000, for EC2-mirroring services — matching Amazon EC2’s own bounds.

MaxResults may not be combined with an explicit list of resource ids. That combination returns InvalidParameterCombination, as it does at Amazon EC2.

The token

NextToken is opaque. Do not parse it, construct it, or store it beyond the sequence it belongs to. Its format may change without notice; nothing about it is documented, because anything documented becomes something a caller depends on.

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 token. This happens whenever filters remove every item from a page, and it is normal.

token = None
while True:
    kwargs = {"MaxResults": 1000}
    if token:
        kwargs["NextToken"] = token
    page = client.describe_instances(**kwargs)
    handle(page["Reservations"])
    token = page.get("NextToken")
    if not token:              # correct
        break
    # if not page["Reservations"]: break   ← wrong; silently loses results

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

Filters

Filters are applied per page, after the page is assembled — not before pagination.

This matches Amazon EC2, and it is why an empty page with a token occurs at all. The alternative, filtering before paginating, would require scanning the entire result set to fill each page.

There is no guarantee that a filtered page is non-empty.

Ordering

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

Consistency

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 not-found.

A caller needing a consistent view must reconcile after the listing completes rather than assuming the listing provided one.

Go further

• Requests and responses
• Errors