Paginate results

This page describes how different Cloud Storage tools and libraries paginate results. Pagination is required when listing a high number of objects or buckets.

The Google Cloud console automatically paginates bucket and object lists in the Buckets and Bucket details pages.


Open the Buckets page

The Google Cloud CLI automatically paginates bucket and object lists.

Client libraries perform pagination by default. When you call a function that supports pagination, an iterator is returned in the response. For an example of how this iterator is used, see the C++ reference documentation for ListObjects().

Client libraries perform pagination by default. When you call a function that supports pagination, an iterator is returned in the response. For an example of how this iterator is used, see the C# reference documentation for ListObjects().

Client libraries perform pagination by default. When you call a function that supports pagination, an iterator is returned in the response. For an example of how this iterator is used, see the Go reference documentation for Bucket.Objects.

Client libraries perform pagination by default. When you call a function that supports pagination, a page token is returned in the response. For an example of how this is used, see the Java reference documentation.

Client libraries perform pagination by default. When you call a function that supports pagination, an iterator is returned in the response. For an example of how this iterator is used, see the Node.js reference documentation for getFiles().

Client libraries perform pagination by default. When you call a function that supports pagination, an iterator is returned in the response. For an example of how this iterator is used, see the PHP reference documentation for Objects.

Client libraries perform pagination by default. When you call a function that supports pagination, an iterator is returned in the response. For an example of how this iterator is used, see the Python reference documentation for page iterators.

Client libraries perform pagination by default. When you call a function that supports pagination, an iterator is returned in the response. For an example of how this iterator is used, see the Ruby reference documentation for Google::Cloud::Storage::File::List.

When you call a function that supports pagination, the continuation token nextPageToken is returned in the response if the listing is incomplete. The nextPageToken represents the last result that's returned. When you pass the value of nextPageToken to the pageToken parameter of a subsequent request, you return the next page of results, starting after the last result.

For example, say your request to list objects in a bucket named my-bucket contains a nextPageToken in the response:

{
  "kind": "storage#objects",
  "nextPageToken": "CgtzaGliYS0yLmpwZw==",
  "items": [
    {
      OBJECT_1_METADATA
    },
    {
      OBJECT_2_METADATA
    },
    …
  ]
}

The HTTP request you would use to continue listing objects in my-bucket would be the following:

GET https://storage.googleapis.com/storage/v1/b/my-bucket/o?pageToken=CgtzaGliYS0yLmpwZw==

For more information on paginating results, see the JSON reference documentation for Objects: list or Buckets: list.

When you call a function that supports pagination, the continuation token NextContinuationToken is returned in the response if the listing is incomplete. The NextContinuationToken represents the last result that's returned. When you pass the value of NextContinuationToken to the continuation-token parameter of a subsequent request, you return the next page of results, starting after the last result.

For example, say your request to list objects in a bucket named my-bucket contains a NextContinuationToken in the response:

<?xml version='1.0' encoding='UTF-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>my-bucket</Name>
  <NextContinuationToken>CgtzaGliYS0yLmpwZw==</NextContinuationToken>
  <KeyCount>2</KeyCount>
  <MaxKeys>2</MaxKeys>
  <IsTruncated>true</IsTruncated>
  <Contents>
    ...
  </Contents>
  ...
</ListBucketResult>

Note that list-type must be set to 2 in order to return a NextContinuationToken when listing objects.

The HTTP request you would use to continue listing objects in my-bucket would include the following:

GET /?continuation-token=CgtzaGliYS0yLmpwZw==&list-type=2 HTTP/1.1
  Host: my-bucket.storage.googleapis.com

For more detailed instructions on paginating through results from a bucket, see the XML reference documentation for List Objects.

Next steps