ListObjects
Returns some or all (up to 1000) of the objects in a bucket.
Description
Deprecated API
The ListObjects operation is maintained for backwards compatibility. For improved functionality and performance, we recommend using the ListObjectsV2 operation instead.
The ListObjects 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.
note
- This operation returns up to 1000 objects at a time. Use the
markerparameter for pagination. - For better performance when listing objects with many prefixes, consider using
delimiterparameter. - If you need to list more than 1000 objects, you should use multiple requests with the
markerparameter.
Request Syntax
GET /?delimiter=Delimiter&encoding-type=EncodingType&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/1.1
Host: BucketName.qstorage.quilibrium.com
x-amz-expected-bucket-owner: OwnerAccountId
Values in italics indicate user input and should be replaced with actual values.
This operation does not have a request body.
Request Parameters
URI Parameters
| Name | Description | Required | Type |
|---|---|---|---|
| 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 called CommonPrefixes | No | text |
| encoding-type | Encoding type used by QStorage to encode object key names in the response | No | text |
| marker | Specifies the key to start with when listing objects in a bucket | No | text |
| max-keys | Sets the maximum number of keys returned in the response body | No | number |
| prefix | Limits the response to keys that begin with the specified prefix | No | text |
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-expected-bucket-owner | The account ID of the expected bucket owner | No | text |
| x-amz-request-payer | Confirms that the requester knows that they will be charged for the request. Valid values: requester | No | text |
Examples
Example 1: List objects in a bucket
GET / HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
x-amz-expected-bucket-owner: 123456789012
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-id-2: Example7qoYGN7uMuFuYS6m7a4l
x-amz-request-id: TX234S0F24A06C7
Date: Wed, 01 Mar 2024 12:00:00 GMT
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
<Name>my-bucket</Name>
<Prefix></Prefix>
<Marker></Marker>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>example.txt</Key>
<LastModified>2024-03-01T12:00:00.000Z</LastModified>
<ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
<Size>11</Size>
<Owner>
<ID>123456789012</ID>
<DisplayName>user@example.com</DisplayName>
</Owner>
</Contents>
</ListBucketResult>
Values in italics indicate variable response values.
Example 2: List objects with a prefix and delimiter
GET /?prefix=documents/&delimiter=/ HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
x-amz-expected-bucket-owner: 123456789012
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-id-2: Example7qoYGN7uMuFuYS6m7a4l
x-amz-request-id: TX234S0F24A06C7
Date: Wed, 01 Mar 2024 12:00:00 GMT
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
<Name>my-bucket</Name>
<Prefix>documents/</Prefix>
<Marker></Marker>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>documents/readme.txt</Key>
<LastModified>2024-03-01T12:00:00.000Z</LastModified>
<ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
<Size>11</Size>
<Owner>
<ID>123456789012</ID>
<DisplayName>user@example.com</DisplayName>
</Owner>
</Contents>
<CommonPrefixes>
<Prefix>documents/2024/</Prefix>
</CommonPrefixes>
</ListBucketResult>
Values in italics indicate variable response values.
Response Syntax
HTTP/1.1 200 OK
x-amz-id-2: RequestId
x-amz-request-id: AmazonRequestId
Date: ISO8601Date
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
<Name>BucketName</Name>
<Prefix>Prefix</Prefix>
<Marker>Marker</Marker>
<MaxKeys>MaxKeys</MaxKeys>
<Delimiter>Delimiter</Delimiter>
<IsTruncated>true|false</IsTruncated>
<Contents>
<Key>ObjectKey</Key>
<LastModified>ISO8601Date</LastModified>
<ETag>EntityTag</ETag>
<Size>Size</Size>
<Owner>
<ID>ID</ID>
<DisplayName>DisplayName</DisplayName>
</Owner>
</Contents>
<CommonPrefixes>
<Prefix>CommonPrefix</Prefix>
</CommonPrefixes>
</ListBucketResult>
Values in italics indicate variable response values.
Response Elements
Response Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-id-2 | An identifier for the request | No | String |
| x-amz-request-id | A unique identifier for the request | No | String |
| Date | The date and time at which the response was sent | No | String |
Response Body Elements
| Name | Description | Required | Type |
|---|---|---|---|
| ListBucketResult | Container for response | No | String |
| Name | Name of the bucket | No | String |
| Prefix | Keys that begin with the indicated prefix | No | String |
| Marker | Indicates where in the bucket listing begins | No | String |
| NextMarker | When the response is truncated (the IsTruncated element value in the response is true), you can use the key name in this field as the marker parameter in the subsequent request to get the next set of objects. QStorage lists objects in alphabetical order. Note: This element is returned only if you have the delimiter request parameter specified. If the response does not include the NextMarker element and it is truncated, you can use the value of the last Key element in the response as the marker parameter in the subsequent request to get the next set of object keys. | No | String |
| MaxKeys | Maximum number of keys returned in the response | No | String |
| Delimiter | Character that groups keys sharing the same string between the prefix and the first occurrence of the delimiter into a single CommonPrefixes element. These grouped keys are not returned elsewhere in the response. Each grouped result counts as only one return against the MaxKeys limit. | No | String |
| IsTruncated | Indicates whether the returned list of objects is truncated | No | String |
| Contents | Contains information about each Object returned. Each Object is returned as a Contents element | No | String |
| EncodingType | Encoding type used by QStorage to encode object key names in the XML response. If specified in the request, this element is included in the response, and encoded key name values are returned in the following response elements: Delimiter, Marker, Prefix, Key, and NextMarker. | No | String |
| CommonPrefixes | Container for keys that are grouped by common prefixes. Only appears when a delimiter is specified. Keys between Prefix and the next occurrence of the delimiter are grouped under a single CommonPrefixes element. These keys act like subdirectories in the directory specified by Prefix (e.g., with prefix 'notes/' and delimiter '/', 'notes/summer/' would be a common prefix). All keys rolled up into a common prefix count as a single return when calculating the number of returns against the 1,000 limit. | No | String |
Special Errors
| Error Code | Description |
|---|---|
| NoSuchBucket | The specified bucket does not exist |
| 403 | Forbidden. Authentication failed or you do not have permission to list objects in the bucket |
Permissions
You must have the s3:ListBucket permission.
Try It Out
Test ListObjects
List objects in a bucket.
Coming Soon
This feature is currently under development and will be available soon.
Related Operations
The following operations are related to ListObjects:
- ListObjectsV2 - The newer, improved version of this operation
- GetObject - Retrieves objects from QStorage
- PutObject - Adds an object to a bucket
- CreateBucket - Creates a new bucket
- ListBuckets - Lists all buckets owned by the authenticated sender