Object Storage API, Amazon S3-compatible REST: ListObjects
Returns a list of bucket objects.
It does not return object contents; use the get method instead.
Output is paginated; you can get a list of up to 1,000 objects per request. If there are more objects, make multiple consecutive requests.
Note
This method has two versions:
listObjectsV2: Current version, which is easier to use.listObjectsV1: Previous version.
Both methods are called using the same URL but with different query parameters. To call listObjectsV2, use the list-type=2 parameter.
For more information on getting started with the API and the general request format, see How to use the S3 API.
listObjectsV2
Request
GET /{bucket}?list-type=2&continuation-token=ContinuationToken&delimiter=Delimiter&encoding-type=EncodingType&max-keys=MaxKeys&prefix=Prefix&start-after=StartAfter HTTP/2
Path parameters
|
Parameter |
Description |
|
|
Bucket name |
Query parameters
All parameters listed in the table are optional.
|
Parameter |
Description |
|
|
Use this parameter to get the next part of the list if all results do not fit in a single response. |
|
|
Delimiter character. If this parameter is specified, Object Storage interprets the key as the path to the file with folders separated by the If the request also specifies the |
|
|
Encoding of server responses. Object Storage can encode responses in the format requested by the client. The possible value is |
|
|
Maximum number of elements in a response. By default, Object Storage outputs no more than 1,000 If the selection criteria are met by more keys than can fit into the output, the response will contain To get all the output elements if their number exceeds |
|
|
String to start the key from. Object Storage selects only those keys which start with Can be used together with |
|
|
Key to start the listing from. |
Headings
Use only common headers in your requests.
Response
Headers
Responses can only contain common headers.
Response codes
For a list of possible responses, see Responses.
A successful response contains additional data in XML format with the schema described below.
Data schema
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
<IsTruncated>boolean</IsTruncated>
<Contents>
<ETag>string</ETag>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Size>integer</Size>
<StorageClass>string</StorageClass>
</Contents>
...
<Name>string</Name>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>
<MaxKeys>integer</MaxKeys>
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<EncodingType>string</EncodingType>
<KeyCount>integer</KeyCount>
<ContinuationToken>string</ContinuationToken>
<NextContinuationToken>string</NextContinuationToken>
<StartAfter>string</StartAfter>
</ListBucketResult>
|
Element |
Description |
|
|
Root element. |
|
|
This flag shows whether all results are returned in the response.
Path: |
|
|
Object description. The response contains as many Path: |
|
|
MD5 hash of the object. No metadata is included in the hash value calculation. Path: |
|
|
Object key. Path: |
|
|
Date and time when the object was last modified. Path: |
|
|
Object size in bytes. Path: |
|
|
Object storage class: Path: |
|
|
Bucket name. Path: |
|
|
Value of the Path: |
|
|
Value of the Path: |
|
|
Value of the Path: |
|
|
Key name part identified when processing the Path: |
|
|
Encoding used by Object Storage to provide a key in an XML response. You will get this tag if the client provided the Path: |
|
|
Number of keys the request returns. Path: |
|
|
Value of the Path: |
|
|
Value to substitute into the Path: |
|
|
Value of the Path: |
listObjectsV1
Request
GET /{bucket}?delimiter=Delimiter&encoding-type=EncodingType&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/2
Path parameters
|
Parameter |
Description |
|
|
Bucket name |
Query parameters
All parameters listed in the table are optional.
|
Parameter |
Description |
|
|
Delimiter character. If this parameter is specified, Object Storage interprets the key as the path to the file with folders separated by the If the request also specifies the |
|
|
Encoding of server responses. Object Storage can encode responses in the format requested by the client. The possible value is |
|
|
Key to start the output from. In the output, Object Storage will leave the keys starting from the one that follows |
|
|
Maximum number of elements in a response. By default, Object Storage outputs no more than 1,000 If the selection criteria are met by more keys than can fit into the output, the response will contain To get all the output elements if their number exceeds |
|
|
String to start the key from. Object Storage selects only those keys which start with Can be used together with |
Headings
Use only common headers in your requests.
Response
Headers
Responses can only contain common headers.
Response codes
For a list of possible responses, see Responses.
A successful response contains additional data in XML format with the schema described below.
Data schema
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
<IsTruncated>boolean</IsTruncated>
<Marker>string</Marker>
<NextMarker>string</NextMarker>
<Contents>
<ETag>string</ETag>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Size>integer</Size>
<StorageClass>string</StorageClass>
</Contents>
...
<Name>string</Name>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>
<MaxKeys>integer</MaxKeys>
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<EncodingType>string</EncodingType>
</ListBucketResult>
|
Element |
Description |
|
|
Root element. |
|
|
This flag shows whether all results are returned in the response.
Path: |
|
|
Value of the Path: |
|
|
Value to substitute into the Path: |
|
|
Object description. The response contains as many Path: |
|
|
MD5 hash of the object. No metadata is included in the hash value calculation. Path: |
|
|
Object key. Path: |
|
|
Date and time when the object was last modified. Path: |
|
|
Object size in bytes. Path: |
|
|
Object storage class: Path: |
|
|
Bucket name. Path: |
|
|
Value of the Path: |
|
|
Value of the Path: |
|
|
Value of the Path: |
|
|
Key name part identified when processing the Path: |
|
|
Encoding used by Object Storage to provide a key in an XML response. You will get this tag if the client provided the Path: |