Paginate results

C++

Client libraries perform pagination by default. When you call a function that supports pagination, the method returns an iterator. You can control the page size by specifying options in the request. 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, the method returns an iterator. You can control the page size by specifying options in the request. 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, the method returns an iterator. You can control the page size using query or pager options. 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, the method returns a page token. You can control the page size using pageSize options. 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, the method returns an iterator. You can control the page size using query options (such as maxResults). 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, the method returns an iterator. You can control the page size using options such as maxResults. 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, the method returns an iterator. You can control the page size using options such as max_results or page_size. 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, the method returns an iterator. You can control the page size using options such as max. For an example of how this iterator is used, see the Ruby reference documentation for Google::Cloud::Storage::File::List.

JSON API

To control the number of results returned per page, use the maxResults query parameter in requests to Objects: list or Buckets: list. For example, to list a maximum of 5 objects at a time:

GET https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?maxResults=5

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.

For example, a request to list objects in BUCKET_NAME might return a nextPageToken in the response:

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

To return the next page of results, starting after the last result, pass the value of nextPageToken to the pageToken parameter of a subsequent request:

GET https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?pageToken=CgtzaGliYS0yLmpwZw==

You can combine maxResults and pageToken in the same request to continue listing with a specific page size.

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

XML API

To control the number of results returned per page, use the max-keys query parameter in requests to List Objects. For example, to list a maximum of 5 objects at a time:

GET /?max-keys=5 HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com

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.

For example, a request to list objects in BUCKET_NAME might return 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 to return a NextContinuationToken when listing objects.

To return the next page of results, starting after the last result, pass the value of NextContinuationToken to the continuation-token parameter of a subsequent request:

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

You can combine max-keys and continuation-token in the same request.

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