GET Bucket (List Objects)

Description

This implementation of the GET operation returns some or all (up to 1000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

To use this implementation of the operation, you must have READ access to the bucket.

Requests

Syntax

GET / HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
Authorization: signatureValue

Request Parameters

This implementation of GET uses the parameters in the following table to return a subset of the objects in a bucket.

Parameter	Description	Required
delimiter	A delimiter is a character you use to group keys. All keys that contain the same string between the prefix and the first occurrence of the delimiter are grouped under a single result element, `CommonPrefixes`. These keys are not returned elsewhere in the response. Type: String Default: None	No
key-marker	Specifies the key to start with when listing objects in a bucket. Amazon S3 lists objects in alphabetical order. Type: String Default: None	No
max-keys	Sets the maximum number of keys returned in the response body. The response might contain fewer keys but will never contain more. If there are additional keys that satisfy the search criteria but were not returned because `max-keys` was exceeded, the response contains `<isTruncated>true</isTruncated>`. To return the additional keys, see `key-marker`. Type: String Default: 1000	No
prefix	Limits the response to keys that begin with the specified prefix. You can use prefixes to separate a bucket into different groupings of keys. (You can think of using `prefix` to make groups in the same way you'd use a folder in a file system.) Type: String Default: None	No

Request Elements

This implementation of the operation does not use request elements.

Request Headers

This implementation of the operation only uses request headers common to all operations. For more information, see Common Request Headers.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

Name	Description
`Contents`	Metadata about each object returned. Type: XML metadata Ancestor: ListBucketResult
`CommonPrefixes`	A response can contain `CommonPrefixes` only if you specify a `delimiter`. When you do, `CommonPrefixes` contains all (if there are any) keys between `Prefix` and the next occurrence of the string specified by `delimiter`. In effect, `CommonPrefixes` lists keys that act like subdirectories in the directory specified by `Prefix`. For example, if `prefix` is `notes/` and `delimiter` is a slash (/), in `notes/summer/july`, the common prefix is `notes/summer/`. All of the keys rolled up in a common prefix count as a single return when calculating the number of returns. See `MaxKeys`. Type: String Ancestor: ListBucketResult
`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. Each rolled up result counts as only one return against the `MaxKeys` value. Type: String Ancestor: ListBucketResult
`DisplayName`	Object owner's name. Type: String Ancestor: ListBucketResult.Contents.Owner
`ETag`	The entity tag is an MD5 hash of the object. The ETag only reflects changes to the contents of an object, not its metadata. Type: String Ancestor: ListBucketResult.Contents
`ID`	Object owner's ID. Type: Boolean Ancestor: ListBucketResult.Contents.Owner
`IsTruncated`	Specifies whether (`true`) or not (`false`) all of the results were returned. All of the results may not be returned if the number of results exceeds that specified by `MaxKeys`. Type: String Ancestor: boolean
`Key`	The object's key. Type: String Ancestor: ListBucketResult.Contents
`LastModified`	Date and time the object was last modified. Type: Date Ancestor: ListBucketResult.Contents
`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
`Name`	Name of the bucket. Type: String Ancestor: ListBucketResult
`Owner`	Bucket owner. Type: String Children: DisplayName, ID Ancestor: ListBucketResult.Contents \| CommonPrefixes
`Prefix`	Keys that begin with the indicated prefix. Type: String Ancestor: ListBucketResult
`Size`	Size in bytes of the object. Type: String Ancestor: ListBucketResult.Contents
`StorageClass`	Always STANDARD. Type: String Ancestor: ListBucketResult.Contents

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Sample Request

This requests returns the objects in BucketName.

GET / HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
Content-Type: text/plain

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
    <Name>bucket</Name>
    <Prefix/>
    <Marker/>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image.jpg</Key>
        <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>&quot;fba9dede5f27731c9771645a39863328&quot;</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>8a6925ce4a7f21c32aa379004fef</ID>
            <DisplayName>mtd@amazon.com</DisplayName>
        </Owner>
    </Contents>
    <Contents>
       <Key>my-third-image.jpg</Key>
         <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>&quot;1b2cf535f27731c974343645a3985328&quot;</ETag>
        <Size>64994</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>8a69b1ddee97f21c32aa379004fef</ID>
            <DisplayName>mtd@amazon.com</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

Sample Request Using Request Parameters

This example lists up to 40 keys in the "quotes" bucket that start with "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  2009 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP
x-amz-request-id: 3B3C7C725673C630
Date: Wed, 01 Mar  2009 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>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
    <Size>5</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>bcaf161ca5fb16fd081034f</ID>
      <DisplayName>webfile</DisplayName>
     </Owner>
  </Contents>
  <Contents>
    <Key>Neo</Key>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
    <Size>4</Size>
    <StorageClass>STANDARD</StorageClass>
     <Owner>
      <ID>bcaf1ffd86a5fb16fd081034f</ID>
      <DisplayName>webfile</DisplayName>
    </Owner>
 </Contents>
</ListBucketResult>

Sample Request Using Prefix and Delimiter

This example lists rolls up all objects for each URI that starts with photos/2006/, has some path element, and ends with the first occurrence of the delimiter "/", for example, each of the following would become a CommonPrefixes entry: photos/2006/January/, photos/2006/February/, and photos/2006/March/

GET ?prefix=photos/2006/&delimiter=/ HTTP/1.1
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar  2009 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <Name>johnsmith</Name>
  <Prefix>photos/2006/</Prefix>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>photos/2006/index.html</Key>
    <LastModified>2009-01-01T12:00:00.000Z</LastModified>
    <ETag>"ce1acdafcc879d7eee54cf4e97334078"</ETag>
    <Size>1234</Size>
    <Owner>
      <ID>214153b66967d86f031c7487b4566cb1b</ID>
      <DisplayName>John Smith</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>photos/2006/January/</Prefix>
  </CommonPrefixes>
</ListBucketResult>

GET Bucket (List Objects)

Description

Requests

Syntax

Request Parameters

Request Elements

Request Headers

Responses

Response Headers

Response Elements

Special Errors

Examples

Sample Request

Sample Response

Sample Request Using Request Parameters

Sample Response

Sample Request Using Prefix and Delimiter

Sample Response

Related Resources