Menu
AWS Command Line Interface
User Guide

Using the AWS Command Line Interface's Pagination Options

For commands that can return a large list of items, the AWS CLI adds three options that you can use to modify the pagination behavior of the CLI when it calls a service's API to populate the list.

By default, the CLI uses a page size of 1000 and retrieves all available items. For example, if you run aws s3api list-objects on an Amazon S3 bucket containing 3500 objects, the CLI makes four calls to Amazon S3, handling the service specific pagination logic in the background.

If you see issues when running list commands on a large number of resources, the default page size may be too high, causing calls to AWS services to time out. You can use the --page-size option to specify a smaller page size to solve this issue. The CLI will still retrieve the full list, but will perform a larger number of calls in the background, retrieving a smaller number of items with each call:

$ aws s3api list-objects --bucket my-bucket --page-size 100
{
    "Contents": [
...

To retrieve fewer items, use the --max-items option. The CLI will handle pagination in the same way, but will only print out the number of items that you specify:

$ aws s3api list-objects --bucket my-bucket --max-items 100
{
    "NextToken": "None___100",
    "Contents": [
...

If the number of items output (--max-items) is fewer than the total number of items, the output includes a NextToken that you can pass in a subsequent command to retrieve the next set of items:

$ aws s3api list-objects --bucket my-bucket --max-items 100 --starting-token None___100
{
    "NextToken": "None___200",
    "Contents": [
...

The starting token is a CLI-specific construct that indicates the page token (if any) and the location of the first item on that page after the output. For example, when you specify a starting token of None___100 in the above example, the CLI retrieves the first page of 1000 items and prints out the next set of items starting with item 100.

After the first page of items is exhausted, the None is replaced by the service-specific pagination token that specifies the current page. You can see this in action by specifying a page-size that is smaller than the number of items that you retrieve:

$ aws s3api list-objects --bucket my-bucket --max-items 10 --page-size 7
{
    "NextToken": "index.html___3",
...

The value of the token varies per service. For Amazon S3 it is the name of the item that starts the page. For other services, like IAM, it may be a randomly generated token:

$ aws iam list-policies --max-items 10 --page-size 7
{
    "NextToken": "AAUqjsdZThJvLdmcMmNUSCGIWM7KRyNFOnLEVqo8q76tU0OW7fXuRKxGSeL1sFPG91dCQqi/FLH+5/Q/eqsY+brttD9FMTWhHH6giSrbKqVm1g==___3",
    "Policies": [
...

If the pagination token is not the name of an object, it's possible that the service doesn't return listings in any guaranteed order. If you specify a next token in the middle of a page, you may see different results that you expect. To prevent this, use the same number for --page-size and --max-items, or retrieve the whole list and perform any necessary parsing operations locally.