ListObjectsV2
Returns some or all (up to 1000) of the objects in a bucket.
Description
The ListObjectsV2 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 operation, you must have s3:ListBucket permissions on the bucket, or be the bucket owner.
note
- This operation returns up to 1000 objects at a time.
- To get the next set of objects, use the
continuation-tokenfrom the previous response. - For better performance when listing objects with many prefixes, use the
delimiterparameter. - A 200 OK response can contain valid or invalid XML.
Request Syntax
GET /?list-type=2&continuation-token=Token&delimiter=Delimiter&encoding-type=EncodingType&fetch-owner=FetchOwner&max-keys=MaxKeys&prefix=Prefix&start-after=StartAfter 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 |
|---|---|---|---|
| list-type | Must be set to 2 to use ListObjectsV2 | Yes | number |
| continuation-token | Token to continue listing more objects. Used for pagination. | No | text |
| delimiter | Character used to group keys | No | text |
| encoding-type | Encoding type used by QStorage to encode object key names in the response | No | text |
| fetch-owner | Specifies whether to include owner information in the response | No | boolean |
| max-keys | Maximum number of keys to return in the response | No | number |
| prefix | Limits the response to keys that begin with the specified prefix | No | text |
| start-after | Start listing after this specified key | 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 /?list-type=2 HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
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>
<KeyCount>2</KeyCount>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>hello.txt</Key>
<LastModified>2024-03-01T11:00:00.000Z</LastModified>
<ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
<Size>11</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
<Contents>
<Key>document.txt</Key>
<LastModified>2024-03-01T11:30:00.000Z</LastModified>
<ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
<Size>11</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
</ListBucketResult>
Values in italics indicate variable response values.
Example 2: List objects with a prefix and delimiter
GET /?list-type=2&prefix=documents/&delimiter=/ HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
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>
<Delimiter>/</Delimiter>
<KeyCount>2</KeyCount>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>documents/report.pdf</Key>
<LastModified>2024-03-01T11:00:00.000Z</LastModified>
<ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
<Size>52428800</Size>
<StorageClass>STANDARD</StorageClass>
</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>
<StartAfter>StartAfter</StartAfter>
<KeyCount>KeyCount</KeyCount>
<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>OwnerId</ID>
<DisplayName>OwnerName</DisplayName>
</Owner>
<StorageClass>StorageClass</StorageClass>
</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 |
| x-amz-request-charged | If present, indicates that the requester was successfully charged for the request. Valid Values: requester | 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 |
| StartAfter | Key to start listing from | No | String |
| KeyCount | Number of keys returned | No | String |
| MaxKeys | Maximum number of keys that could have been returned | No | String |
| Delimiter | Character used to group keys. Keys containing the same string between the prefix and the first occurrence of the delimiter are grouped under a single CommonPrefixes element. These grouped keys are not listed individually elsewhere in the response and each group counts as one item 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 |
| Key | The object key | No | String |
| LastModified | Date and time the object was last modified | No | String |
| ContinuationToken | If ContinuationToken was sent with the request, it is included in the response. You can use this ContinuationToken for pagination of the list results. | No | String |
| NextContinuationToken | Token to use in a subsequent request to get the next set of objects, if there are any remaining. | No | String |
| ETag | The entity tag is an MD5 hash of the object | No | String |
| EncodingType | Encoding type used 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, Prefix, Key, and StartAfter. | No | String |
| Size | Size in bytes of the object | No | String |
| Owner | Bucket owner information | No | String |
| StorageClass | Storage class used for storing the object | No | String |
| CommonPrefixes | Groups of keys that share identical patterns up to the next delimiter character. These common prefixes only appear in the response when a delimiter parameter is specified. | 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 |
Permissions
You must have the s3:ListBucket permission.
Try It Out
Test ListObjectsV2
List objects in a bucket.
Coming Soon
This feature is currently under development and will be available soon.