Get started
Log in
Yandex Object Storage

listObjects method

Returns a list of objects in a bucket.

Pagination is used for output. You can get a list of up to 1,000 objects per request. If there are more objects, make several consecutive requests.

Request

GET /{bucket} HTTP/1.1

Path parameters

Parameter Description
bucket Bucket name.

Query parameters

All the parameters listed in the table are optional.

Parameter Description
delimiter Delimiter character.

If this parameter is specified, Object Storage interprets the key as the path to the file with folders separated by the delimiter character. In response to the request, the user will get a list of files and folders in the bucket. The files will be output in the Contents elements, and the folders will be in the CommonPrefixes elements.

If the request also specifies the prefix parameter, Object Storage will return the list of files and folders in the prefix folder.
marker Key to start the output from.

In the resulting output, Object Storage leaves the keys starting from the one following the marker.
max-keys Maximum number of elements in a response.

By default, Object Storage outputs no more than 1,000 Contents and CommonPrefixes elements. This parameter should be used if you need to get less than 1,000 elements in a single response.

If the number of keys meeting the selection criteria is greater than the number that could fit in the output, the response contains <IsTruncated>true</IsTruncated>.

To get all output elements if there are more than the max-keys value, make several consecutive requests to Object Storage with the marker parameter, where for each request, the marker is equal to the value of the MaxKeys element from the previous response.
prefix String to start the key from.

Object Storage selects only those keys which start with prefix.

Can be used simultaneously with the delimiter parameter. In this case, the output logic is the same as that specified in the delimiter parameter description.

Headers

In a request, use only common request headers.

Response

Headers

A response can only contain common response 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>
    <Name>bucket</Name>
    <Prefix/>
    <Marker/>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image.jpg</Key>
        <LastModified>2018-09-10T17:50:30.000Z</LastModified>
        <ETag>MD5</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
</ListBucketResult>
Element Description
Contents Object description.

The response will contain as many Contents elements as there are keys that meet the request criteria.

Path: /ListBucketResult/Contents.
CommonPrefixes Part of the key name that is identified when processing the delimiter and prefix path parameters.

Path: /ListBucketResult/CommonPrefixes.
Delimiter Value of the delimiter path parameter.

Path: /ListBucketResult/Delimiter.
ETag MD5 hash of the object. No metadata is included in the hash value calculation.

Path: /ListBucketResult/Contents/ETag.
IsTruncated Flag indicating whether all results are returned in the response.

True — all. False — not all.

Path: /ListBucketResult/IsTruncated.
Key Object key.

Path: /ListBucketResult/Contents/Key.
LastModified Date and time when the object was last modified.

Path: /ListBucketResult/Contents/LastModified.
Marker Value of the marker path parameter.

Path: /ListBucketResult/Marker.
MaxKeys Value of the max-keys path parameter.

Path: /ListBucketResult/MaxKeys.
Name Bucket name.

Path: /ListBucketResult/Name.
NextMarker Value to insert in the marker path parameter to get the next part of the list if the entire list does not fit in the current response.

Path: /ListBucketResult/NextMarker.
Prefix Value of the prefix path parameter.

Path: /ListBucketResult/Prefix.
Size Object size in bytes.

Path: /ListBucketResult/Contents/Size.
StorageClass Object storage class: STANDARD or COLD.

Path: /ListBucketResult/Contents/StorageClass.