GET Bucket

Description

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.

Requests

Syntax

GET ?prefix=prefix;marker=marker;max-keys=max-keys;delimiter=delimiter HTTP/1.1

Host: destinationBucket.s3.amazonaws.com

Date: date

Authorization: signature

Parameters

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

Responses

Success Response

Syntax

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>&quot;etag&quot;</ETag>

    <Size>size</Size>

    <StorageClass>STANDARD</StorageClass>

    <Owner>

      <ID>owner_id</ID>

      <DisplayName>owner_name</DisplayName>

     </Owner>

  </Contents>

  ...

</ListBucketResult>

Elements

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

Special Errors

There are no special errors for this operation. For information about general Amazon S3 errors, see List of Error Codes.

Examples

Sample Request

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=

Sample Response

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>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</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>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>

    <Size>4</Size>

    <StorageClass>STANDARD</StorageClass>

     <Owner>

      <ID>bcaf1ffd86f41caff1a493dc2ad8c2c281e37522a640e161ca5fb16fd081034f</ID>

      <DisplayName>webfile</DisplayName>

    </Owner>

 </Contents>

</ListBucketResult>

Related Resources

GET Object
PUT Object
DELETE Object