Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

Object Storage API, Amazon S3-compatible REST: ListObjects

Written by
Improved by
Updated at May 6, 2026

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 Bucket name.

Query parameters

All parameters listed in the table are optional.

Parameter Description
continuation-token Use to get the next part of the list if all results do not fit into 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 a file path, where folders are separated by the delimiter character. In the response, 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 per 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 per response.

If the selection criteria are met by more keys than the output has room for, the response contains <IsTruncated>true</IsTruncated>.

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

Object Storage will select only keys that start with prefix.

Can be used at the same time with the delimiter parameter. 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 Flag showing whether or not the response contains all the results.

True for not all, False for all.

Path: /ListBucketResult/IsTruncated.
Contents Object description.

The response will contain 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 returned by the request.
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 substitute to the continuation-token query parameter to get the next part of the list, if the entire list does not fit into the current response.
It is returned only when 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 a file path, where folders are separated by the delimiter character. In the response, 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 the output starts from.

In the output, Object Storage will leave the keys starting from the one that follows marker.
max-keys Maximum number of elements per 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 per response.

If the selection criteria are met by more keys than the output has room for, the response contains <IsTruncated>true</IsTruncated>.

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

Object Storage will select only keys that start with prefix.

Can be used at the same time with the delimiter parameter. 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 Flag showing whether or not the response contains all the results.

True stands for not all, False stands for all.

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

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

Path: /ListBucketResult/NextMarker.
Contents Object description.

The response will contain 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
HeadBucket
Next
ListBuckets