A GET request operation using a bucket URI lists information about the objects in the bucket.
To list the keys of a bucket, you must have READ access to the bucket.
For a general introduction to the list operation, see Listing Keys.
GET ?prefix=prefix;marker=marker;max-keys=max-keys;delimiter=delimiterHTTP/1.1 Host:destinationBucket.s3.amazonaws.com Date:dateAuthorization:signature
| Name | Description | Required |
|---|---|---|
prefix
|
Limits the response to keys which begin with the indicated prefix. You can use prefixes to separate a bucket into different sets of keys in a way similar to how a file system uses folders. Type: String Default: None Constraints: None | No |
marker
|
Indicates where in the bucket to begin listing. The list will only include keys that occur lexicographically after marker. This is convenient for pagination: To get the next page of results use the last key of the current page as the marker. Type: String Default: None Constraints: None | No |
max-keys
|
The maximum number of keys you'd like to see in the response body. The server might return fewer than this many keys, but will not return more. Type: String Default: None Constraints: None | No |
delimiter
|
Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys are not returned elsewhere in the response. Type: String Default: None Constraints: None | No |
HTTP/1.1 200 OK x-amz-id-2: id x-amz-request-id: request_id Date: date Content-Type: type Content-Length: length Connection: close Server: AmazonS3 <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01"> <Name>bucket</Name> <Prefix>prefix</Prefix> <Marker>marker</Marker> <MaxKeys>max-keys</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>object</Key> <LastModified>date;</LastModified> <ETag>"etag"</ETag> <Size>size</Size> <StorageClass>STANDARD</StorageClass> <Owner> <ID>owner_id</ID> <DisplayName>owner_name</DisplayName> </Owner> </Contents> ... </ListBucketResult>
| Name | Description |
|---|---|
Name
|
Name of the bucket. Type: String Ancestor: ListBucketResult |
Prefix
|
Keys that begin with the indicated prefix. Type: String Ancestor: ListBucketResult |
Marker
|
Indicates where in the bucket to begin listing. Type: String Ancestor: ListBucketResult |
MaxKeys
|
The maximum number of keys returned in the response body. Type: String Ancestor: ListBucketResult |
Delimeter
|
Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys are not returned elsewhere in the response. Type: String Ancestor: ListBucketResult |
Contents
|
Metadata about each object returned. Type: XML metadata Ancestor: ListBucketResult |
There are no special errors for this operation. For information about general Amazon S3 errors, see List of Error Codes.
This example lists up to 40 keys in the "quotes" bucket that have the prefix "N" and occur lexicographically after "Ned".
GET ?prefix=N&marker=Ned&max-keys=40 HTTP/1.1 Host: quotes.s3.amazonaws.com Date: Wed, 01 Mar 2006 12:00:00 GMT Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
HTTP/1.1 200 OK
x-amz-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP
x-amz-request-id: 3B3C7C725673C630
Date: Wed, 01 Mar 2006 12:00:00 GMT
Content-Type: application/xml
Content-Length: 302
Connection: close
Server: AmazonS3
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Name>quotes</Name>
<Prefix>N</Prefix>
<Marker>Ned</Marker>
<MaxKeys>40</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>Nelson</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>5</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>bcaf1ffd86f41caff1a493dc2ad8c2c281e37522a640e161ca5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>Neo</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>4</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>bcaf1ffd86f41caff1a493dc2ad8c2c281e37522a640e161ca5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
</Contents>
</ListBucketResult>