To list the objects in a bucket you make a GET request that is scoped to a bucket. You can also use query string parameters to further scope the request. The request returns the list of objects in an XML document in the response body, and objects in the list are ordered lexicographically by name.
You must have bucket READ permission to get the list of objects that are in a
bucket, and you must have bucket FULL_CONTROL permission to list a bucket's
ACLs or CORS.
You can restrict and organize the list of objects returned in a GET Bucket
request by using the delimiter, marker, max-keys, and prefix query
string parameters.
The XML API does not return lists longer than 1000 objects.
Query string parameters
| Parameter | Description | Required |
|---|---|---|
delimiter |
A character or multiple characters that can be used to simplify a list
of objects that use a directory-like naming scheme. Can be used in
conjunction with a prefix. |
No |
encoding-type |
When set to url, object names are URL-encoded in the
response. |
No |
generation-marker |
The object generation after which you want to start listing objects. If you use generation-marker, you must also use marker. | No |
marker |
The object name after which you want to start listing objects. Objects
whose names are lexicographically greater than the marker
are returned in the list of objects. |
No |
max-keys |
The maximum number of objects to return in a list object request. | No |
prefix |
A string that can be used to limit the number of objects that are
returned in a GET Bucket request to only those whose names begin with the
specified value. Can be used in conjunction with a
delimiter. |
No |
versions |
If specified on a versioned bucket, returns the list of all object versions. If omitted, only lists current versions. | No |
Request headers
Request body elements
This request does not include an XML document in the request body.
Request syntax
The following syntax applies to GET Bucket requests that use either no
parameters, or one or more of the delimiter, generation-marker, marker,
max-keys, prefix, and versions query string parameters.
GET /?prefix=a_prefix&marker=a_marker&max-keys=max_number_of_keys&delimiter=a_delimiter HTTP/1.1 Host: <bucket>.storage.googleapis.com Date: <date> Content-Length: <request body length> Authorization: <authentication string>
Response headers
The request can return a variety of response headers depending on the request headers you use.
Response body elements
The following response body elements are applicable only if you use either
no parameters, or one or more of the delimiter, generation-marker, marker,
max-keys, prefix, or versions query string parameters to list objects in
a bucket.
| Element | Description |
|---|---|
ListBucketResult |
Container for the object information you are requesting. |
Name |
The bucket name. |
CommonPrefixes |
Container for prefixes that satisfy your prefix and
delimiter constraints. This container is used only if you
specify a delimiter in the request, and duplicate entries
are omitted. |
Delimiter |
The delimiter that you specified in the request. |
MaxKeys |
The max-keys that you specified in the request. |
Prefix |
The prefix that you specified in the request. |
GenerationMarker |
The generation-marker that you specified in the request. |
NextGenerationMarker |
If the list of returned objects is incomplete and versions parameter was used, NextGenerationMarker provides the generation of the last object that was returned. If the list is already complete, NextGenerationMarker is not returned. |
Marker |
The marker that you specified in the request. |
NextMarker |
NextMarker provides the name of the last object that was returned. The value of NextMarker can be provided in the marker query string parameter in a future GET Bucket call to continue listing the Bucket after this set of results. If there are no more objects in the Bucket that follow the last object in the list, NextMarker is not returned. |
IsTruncated |
Indicates whether or not all of the objects in a bucket appear on the list. If max-keys is less than the number of objects in a bucket, this element is True. |
Contents |
Container for object information if versions query parameter is not used. |
Version |
Container for object information if versions query parameter is used. |
Key |
The name of an object. |
Generation |
The generation of the object. |
MetaGeneration |
Generation of the metadata of the object. |
IsLatest |
If versions query parameter specified, this is set to true if the object is currently live. Live meaning that if this object is requested without generation, this object is returned. |
LastModified |
The date and time that the object metadata was last modified. |
DeletedTime |
If versions query parameter was specified, contains the date and time that an object was overwritten or deleted for non-current objects (if the bucket has versioning enabled). |
ETag |
An HTTP 1.1 entity tag for the object. |
Size |
Size of the object in bytes. |
KmsKeyName |
The name of the KMS key used to encrypt the object. This element is only present if the object is encrypted with Customer-Managed Encryption Keys. |
Examples
The following sample lists the objects in a bucket named travel-maps.
Request
GET / HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Wed, 17 Feb 2010 15:31:56 GMT Content-Length: 0 Content-Type: text/plain Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/1.1 200 OK
Content-Length: 4061
Content-Type: application/xml
Date: Wed, 17 Feb 2010 23:31:57 GMT
Expires: Wed, 17 Feb 2010 23:31:57 GMT
<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
<Name>travel-maps</Name>
<Prefix></Prefix>
<Marker></Marker>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>europe/france/cannes.pdf</Key>
<Generation>1360887759327000</Generation>
<MetaGeneration>1</MetaGeneration>
<LastModified>2010-02-17T22:11:12.487Z</LastModified>
<ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
<Size>5061631</Size>
</Contents>
<Contents>
<Key>europe/france/paris.pdf</Key>
<Generation>1360887759329000</Generation>
<MetaGeneration>1</MetaGeneration>
<LastModified>2010-02-17T22:09:57.457Z</LastModified>
<ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
<Size>5061631</Size>
</Contents>
</ListBucketResult>
The following sample lists the objects in travel-maps, but it restricts the list to 25 objects that begin with the letter "t" and come after "test".
Request
GET /?prefix=t&marker=test&max-keys=25 HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Mon, 16 Feb 2010 22:58:38 GMT Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 2705
Content-Type: application/xml
<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
<Name>travel-maps</Name>
<Prefix>t</Prefix>
<Marker>test</Marker>
<MaxKeys>25</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>test_a.jpg</Key>
<Generation>1360887659329000</Generation>
<MetaGeneration>1</MetaGeneration>
<LastModified>2010-02-17T03:12:55.561Z</LastModified>
<ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
<Size>328</Size>
</Contents>
<Contents>
<Key>test_b.jpg</Key>
<Generation>1360887659323000</Generation>
<MetaGeneration>1</MetaGeneration>
<LastModified>2010-02-17T03:12:54.606Z</LastModified>
<ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
<Size>328</Size>
</Contents>
<Contents>
<Key>test_c.jpg</Key>
<LastModified>2010-02-17T03:12:53.734Z</LastModified>
<ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
<Size>328</Size>
</Contents>
</ListBucketResult>
Example using prefix and delimiter
The following example uses a prefix and a delimiter to return a list of
objects that are named using a directory-like schema. By using prefix=europe/
and delimiter=/, only those objects that are in the europe/ "directory" are
returned. Objects that are in "subdirectories" of the europe directory are not
listed, but instead have the leading portion of their names included in the
CommonPrefixes elements of the response. The sample assumes that the following
objects are contained in a bucket named travel-maps:
- africa/ghana.jpg
- africa/egypt/cairo.jpg
- europe/finland.jpg
- europe/norway.jpg
- europe/france/paris.jpg
- europe/italy/rome.jpg
- europe/sweden/stockholm.jpg
- europe/sweden/stockholm/nordic_museum.jpg
The sample request returns an XML document that lists the following two objects
in the Contents element:
- europe/finland.jpg
- europe/norway.jpg
The following europe subdirectories are listed in the CommonPrefixes element:
- europe/france/
- europe/italy/
- europe/sweden/
Request
GET /travel-maps?delimiter=/&prefix=europe/ HTTP/1.1 Host: storage.googleapis.com Date: Mon, 16 Feb 2010 22:58:38 GMT Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 1200
Content-Type: application/xml
<?xml version="1.0"?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
<Name>mybucket</Name>
<Prefix>europe/</Prefix>
<Marker />
<IsTruncated>false</IsTruncated>
<Contents>
<Key>europe/finland.jpg</Key>
<Generation>1360887659323000</Generation>
<MetaGeneration>1</MetaGeneration>
<LastModified>2010-02-17T03:12:55.561Z</LastModified>
<ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
<Size>10</Size>
</Contents>
<Contents>
<Key>europe/norway.jpg</Key>
<Generation>1360887659323000</Generation>
<MetaGeneration>1</MetaGeneration>
<LastModified>2010-02-17T03:12:55.561Z</LastModified>
<ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
<Size>10</Size>
</Contents>
<CommonPrefixes>
<Prefix>europe/france/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>europe/italy/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>europe/sweden/</Prefix>
</CommonPrefixes>
</ListBucketResult>