Contact UsGet started

listObjects method

Written by
Improved by
Updated at October 29, 2024

Returns a list of bucket objects.

It does not return object contents. To get them, use the get method.

Pagination is used for output. 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.

The same URL, with different query parameters, is used to call both methods. 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 Bucket name.

Query parameters

All parameters listed in the table are optional.

Parameter Description
continuation-token Use this parameter to get the next part of the list if all results do not fit in a single response.
To get the next part of the list, use the NextContinuationToken value from the previous response.
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. Files will be output in the Contents elements, and folders, in the CommonPrefixes elements.

If the request also specifies the prefix parameter, Object Storage will return a list of files and folders in the prefix folder.
encoding-type Encoding of server responses.

Object Storage can encode responses in the format requested by the client.

Possible values: url.
max-keys Maximum number of elements in a response.

By default, Object Storage outputs no more than 1,000 Contents and CommonPrefixes elements. Use this parameter if you need fewer than 1,000 elements in a single response.

If the selection criteria are met by more keys than can fit into the output, the response will contain <IsTruncated>true</IsTruncated>.

To get all the output elements if their number exceeds max-keys, run multiple requests to Object Storage with the continuation-token parameter, where the continuation-token of each request is equal to the value of the NextContinuationToken element in the previous response.
prefix String to start the key from.

Object Storage selects only those keys which start with prefix.

You can use this parameter at the same time with delimiter. In this case, the output logic is determined by the delimiter parameter.
start-after Key to start the listing from.

Headers

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
ListBucketResult Root element.
IsTruncated This flag shows whether all results are returned in the response.

True means not all, False stands for all.

Path: /ListBucketResult/IsTruncated.
Contents Object description.

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

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

Path: /ListBucketResult/Contents/ETag.
Key Object key.

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

Path: /ListBucketResult/Contents/LastModified.
Size Object size in bytes.

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

Path: /ListBucketResult/Contents/StorageClass.
Name Bucket name.

Path: /ListBucketResult/Name.
Prefix Value of the prefix query parameter.

Path: /ListBucketResult/Prefix.
Delimiter Value of the delimiter query parameter.

Path: /ListBucketResult/Delimiter.
MaxKeys Value of the max-keys query parameter.

Path: /ListBucketResult/MaxKeys.
CommonPrefixes Key name part identified when processing the delimiter and prefix query parameters.

Path: /ListBucketResult/CommonPrefixes.
EncodingType Encoding used by Object Storage to provide a key in an XML response.

You will get this tag if the client provided the encoding-type parameter in the request.

Path: /ListBucketResult/EncodingType.
KeyCount Number of keys the request returns.
The number of keys is always less than or equal to MaxKeys.

Path: /ContinuationToken/KeyCount.
ContinuationToken Value of the continuation-token query parameter.

Path: /ContinuationToken/ContinuationToken.
NextContinuationToken Value to insert in the continuation-token query parameter to get the next part of the list if the entire list does not fit in the current response.
It is returned only in case IsTruncated = true.

Path: /ListBucketResult/NextContinuationToken.
StartAfter Value of the start-after query parameter.

Path: /ListBucketResult/StartAfter.

listObjectsV1

Request

GET /{bucket}?delimiter=Delimiter&encoding-type=EncodingType&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/2

Path parameters

Parameter Description
bucket Bucket name.

Query parameters

All 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. Files will be output in the Contents elements, and folders, in the CommonPrefixes elements.

If the request also specifies the prefix parameter, Object Storage will return a list of files and folders in the prefix folder.
encoding-type Encoding of server responses.

Object Storage can encode responses in the format requested by the client.

Possible values: url.
marker Key to start the output from.

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

By default, Object Storage outputs no more than 1,000 Contents and CommonPrefixes elements. Use this parameter if you need fewer than 1,000 elements in a single response.

If the selection criteria are met by more keys than can fit into the output, the response will contain <IsTruncated>true</IsTruncated>.

To get all the output elements if their number exceeds max-keys, run multiple requests to Object Storage with the marker parameter, where the marker of each request is equal to the value of the NextMarker element in the previous response.
prefix String to start the key from.

Object Storage selects only those keys which start with prefix.

You can use this parameter at the same time with delimiter. In this case, the output logic is determined by the delimiter parameter.

Headers

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
ListBucketResult Root element.
IsTruncated This flag shows whether all results are returned in the response.

True means not all, False stands for all.

Path: /ListBucketResult/IsTruncated.
Marker Value of the marker query parameter.

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

Path: /ListBucketResult/NextMarker.
Contents Object description.

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

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

Path: /ListBucketResult/Contents/ETag.
Key Object key.

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

Path: /ListBucketResult/Contents/LastModified.
Size Object size in bytes.

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

Path: /ListBucketResult/Contents/StorageClass.
Name Bucket name.

Path: /ListBucketResult/Name.
Prefix Value of the prefix query parameter.

Path: /ListBucketResult/Prefix.
Delimiter Value of the delimiter query parameter.

Path: /ListBucketResult/Delimiter.
MaxKeys Value of the max-keys query parameter.

Path: /ListBucketResult/MaxKeys.
CommonPrefixes Key name part identified when processing the delimiter and prefix query parameters.

Path: /ListBucketResult/CommonPrefixes.
EncodingType Encoding used by Object Storage to provide a key in an XML response.

You will get this tag if the client provided the encoding-type parameter in the request.

Path: /ListBucketResult/EncodingType.

See also

Previous
getMeta
Next
listBuckets