List objects in a given bucket

Edit online

A GET request addressed to a bucket returns a list of objects, limited to 1,000 at a time and returned in non-lexographical order. The StorageClass value that is returned in the response is the storage class set in the COS Manager in container mode, or the default value if no storage class is set or in vault mode.

Syntax


GET https://{endpoint}/{bucket-name} # path style
GET https://{bucket-name}.{endpoint} # virtual host style

Optional request header

Table 1. Request header
Name	Description	Required
Mirror-Destination	This header is applicable for listing of buckets in a protected mirror. The Mirror-Destination header specifies from which vault of the mirror to read. By default, if no explicit vault is specified, then the listing request will attempt to read from both vaults and provide a listing response that combines the list of objects on each component vault to the mirror excluding duplicates (object resides on both vaults in the mirror). If the Mirror-Destination header is specified and includes a valid Vault Identifier, the data returned will be from the Vault with the ID that matches what was provided in the header. The Mirror-Destination header is applicable only to protected mirrors, and the header is ignored otherwise. A failure to read from the specified vault will result in an error back to the HTTP client. Type String Default None Constraints {Valid Vault Identifier}	No

Optional query parameters

Name	Type	Description
`prefix`	string	Constrains response to object names beginning with `prefix`.
`delimiter`	string	Groups objects between the `prefix` and the `delimiter`.
`encoding-type`	string	If unicode characters that are not supported by XML are used in an object name, this parameter can be set to `url` to properly encode the response.
`max-keys`	string	Restricts the number of objects to display in the response. Default and maximum is 1,000.
`marker`	string	Specifies the object from where the listing should begin, in UTF–8 binary order.

Sample request

This request lists the objects inside the “example” bucket.


GET /example-bucket HTTP/1.1
Content-Type: text/plain
Host: 67.228.254.193
X-Amz-Date: 20160822T225156Z
Authorization: {authorization-string}

Sample response


HTTP/1.1 200 OK
Date: Wed, 24 Aug 2016 17:36:24 GMT
X-Clv-Request-Id: 9f39ff2e-55d1-461b-a6f1-2d0b75138861
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.115
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f39ff2e-55d1-461b-a6f1-2d0b75138861
Content-Type: application/xml
Content-Length: 909


<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>example-bucket</Name>
  <Prefix/>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <Delimiter/>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>object-1</Key>
    <LastModified>2016-08-25T17:38:38.549Z</LastModified>
    <ETag>"0cbc6611f5540bd0809a388dc95a615b"</ETag>
    <ChecksumAlgorithm>CRC64NVME</ChecksumAlgorithm>
    <ChecksumType>FULL_OBJECT</ChecksumType>
    <Size>4</Size>
    <Owner>
      <ID>{access-key}</ID>
      <DisplayName>{username}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>soldier-bee</Key>
    <LastModified>2016-08-25T17:49:06.006Z</LastModified>
    <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag>
    <ChecksumAlgorithm>CRC64NVME</ChecksumAlgorithm>
    <ChecksumType>FULL_OBJECT</ChecksumType>
    <Size>11</Size>
    <Owner>
      <ID>{access-key}</ID>
      <DisplayName>{username}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>worker-bee</Key>
    <LastModified>2016-08-25T17:46:53.288Z</LastModified>
    <ETag>"d34d8aada2996fc42e6948b926513907"</ETag>
    <ChecksumAlgorithm>CRC64NVME</ChecksumAlgorithm>
    <ChecksumType>FULL_OBJECT</ChecksumType>
    <Size>467</Size>
    <Owner>
      <ID>{access-key}</ID>
      <DisplayName>{username}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>