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.

Console

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


Open the Buckets page

Command line

The Google Cloud CLI automatically paginates bucket and object lists.

Client libraries

C++

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().

C#

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().

Go

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.

Java

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.

Node.js

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().

PHP

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.

Python

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.

Ruby

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.

REST APIs

JSON API

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.

XML API

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