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.
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
nextPageTokenvalue 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
NextContinuationTokenvalue 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.