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, an iterator is returned in the response. For an example of how this iterator is used, see the Java reference documentation for Storage.Objects.list.

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.

Example response

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

For more information about objects Resource, see the Objects reference documentation.

Example request

GET https://storage.googleapis.com/storage/v1/b/BUCKET_NAME&pageToken=NEXT_PAGE_TOKEN HTTP/1.1

Authorization: Bearer ACCESS_TOKEN
Accept: application/json

Where:

  • NEXT_PAGE_TOKEN is the nextPageToken value from the previous response.
  • BUCKET_NAME is the name of your storage bucket.
  • ACCESS_TOKEN is the access token you receive from the OAuth 2.0 Playground.

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.

Example response

HTTP/1.1 200 OK
X-goog-metageneration: 5
Content-location: https://example-bucket.storage.googleapis.com?max-keys=2&list-type=2
Expires: Wed, 02 Mar 2022 15:58:11 GMT
Content-length: 781
X-guploader-uploadid: ADPycdvFss2qs9wyMrrM2fIIZzTFFnZZM9i9k8TMbHipsxz8PqUjS5Xh_4tLsvb3_YYHTT0HmSYVv1Gtr816HQFnk28HMglyWA
Cache-control: private, max-age=0
Date: Wed, 02 Mar 2022 15:58:11 GMT
Content-type: application/xml; charset=UTF-8

<?xml version='1.0' encoding='UTF-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>example_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.

Example request

GET /?continuation-token=NEXT_CONTINUATION_TOKEN&prefix=t&marker=test&list-type=2 HTTP/1.1 \
  Host: BUCKET_NAME.storage.googleapis.com
  Date: Wed, 02 Mar 2022 16:00:00 GMT
  Content-Length: 0
  Authorization: AUTHENTICATION_STRING

Where:

  • NEXT_CONTINUATION_TOKEN is the NextContinuationToken value you receive from the previous response.
  • BUCKET_NAME is the name of your storage bucket.
  • AUTHENTICATION_STRING is the access token you receive from the OAuth 2.0 Playground.

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

Next steps