Yandex.Cloud
  • Services
  • Why Yandex.Cloud
  • Pricing
  • Documentation
  • Contact us
Get started
Yandex Object Storage
  • Getting started
  • Step-by-step instructions
    • All instructions
    • Buckets
      • Creating a bucket
      • Deleting a bucket
      • Limiting the maximum size of a bucket
      • Allowing public access to a bucket
      • Bucket encryption
      • Managing object lifecycles
      • Managing CORS configurations
      • Editing a bucket ACL
      • Logging actions with the bucket
    • Objects
      • Uploading an object
      • Getting information about an object
      • Downloading an object
      • Getting a public link to an object
      • Deleting an object
      • Deleting a partially uploaded object
      • Editing an object ACL
    • Static website hosting
      • Hosting setup
      • Support for your own domain
      • Support for multiple domain names
      • Configuring HTTPS
  • Concepts
    • Overview
    • Bucket
    • Objects
    • Bucket versioning
    • Object lifecycles
    • CORS
    • Static website hosting
    • Pre-signed URLs
    • Multipart upload
    • Access control lists (ACLs)
    • Bucket Policy
    • Upload file via HTML form
    • Storage class
    • Logging actions with a bucket
    • Backups
    • TLS protocol
    • Quotas and limits
  • Tools
    • All tools
    • Console clients
      • AWS CLI
      • S3cmd
    • File browsers
      • CyberDuck
      • WinSCP
    • SDK
      • AWS SDK for Java
      • Python SDK (boto)
    • FUSE
      • s3fs
      • goofys
  • Amazon S3-compatible HTTP API
    • How to use the API
    • Signing requests
    • API reference
      • All services and methods
      • Bucket
        • All methods
        • create
        • getBucketEncryption
        • getMeta
        • listObjects
        • listBuckets
        • deleteBucket
        • deleteBucketEncryption
        • putBucketEncryption
        • putBucketVersioning
        • getBucketVersioning
        • putBucketLogging
        • getBucketLogging
        • listObjectVersions
      • Object
        • All methods
        • upload
        • get
        • copy
        • getObjectMeta
        • delete
        • deleteMultipleObjects
        • options
      • Multipart upload
        • General multipart upload procedure
        • startUpload
        • uploadPart
        • copyPart
        • listParts
        • abortUpload
        • completeUpload
        • listUploads
      • Static Website Hosting
        • All methods
        • upload
        • get
        • delete
        • Static website response codes
      • CORS
        • All methods
        • XML structure of CORS configuration
        • upload
        • get
        • delete
      • Lifecycles
        • All methods
        • XML structure of lifecycle configuration
        • upload
        • get
        • delete
      • ACL
        • All methods
        • XML structure of ACL configuration
        • objectGetAcl
        • objectPutAcl
        • bucketGetAcl
        • bucketPutAcl
      • Bucket Policy
        • All methods
        • GetBucketPolicy
        • PutBucketPolicy
        • DeleteBucketPolicy
        • Data schema
        • Actions
        • Conditions
      • Common request headers
      • Common response headers
      • Responses
  • Access management
  • Pricing policy
    • Current pricing policy
    • Archive
      • Before January 1, 2019
      • From January 1 to March 1, 2019
  • Questions and answers
  1. Amazon S3-compatible HTTP API
  2. API reference
  3. Bucket
  4. listObjects

listObjects method

  • listObjectsV2
    • Request
    • Response
  • listObjectsV1
    • Request
    • Response

Returns a list of bucket objects.

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

Note

This method has two versions.

  • listObjectsV2: Current version, 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.

listObjectsV2

Request

GET /{bucket}?list-type=2&continuation-token=ContinuationToken&delimiter=Delimiter&encoding-type=EncodingType&max-keys=MaxKeys&prefix=Prefix&start-after=StartAfter HTTP/1.1

Path parameters

Parameter Description
bucket Bucket name.

Query parameters

All the parameters listed in the table are optional.

Parameter Description
continuation-token Used to get the next part of the list if all the results don't fit in a single response.
To get the next part of the list, use the NextContinuationToken value from the previous answer.
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 gets a list of files and folders in the bucket. Files are output in the Contents elements, and folders in the CommonPrefixes elements.

If the request also specifies the prefix parameter, Object Storage returns 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 returns a maximum of 1000 Contents and CommonPrefixes elements. This parameter should be used if you need to get less than 1000 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 their number exceeds the max-keys value, make several consecutive requests to Object Storage with the continuation-token parameter, where, for each request, the continuation-token is equal to the value of the NextContinuationToken element from the previous response.
prefix String to start the key from.

Object Storage selects only those keys that start with prefix.

Can be used simultaneously with the delimiter parameter. In this case, the output logic is determined by the delimiter parameter.
start-after The key to start the listing from.

Headers

Use only common request headers in requests.

Response

Headers

Responses 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>
   <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 indicating whether all results are returned in the response.

True: All.False: Not 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 or COLD.

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 Part of the key name that is identified when processing the delimiter and prefix query parameters.

Path: /ListBucketResult/CommonPrefixes.
EncodingType Encoding in which Object Storage provides a key in the XML response.

Appears if the client passed the encoding-type parameter in the request.

Path: /ListBucketResult/EncodingType.
KeyCount The 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 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.
This value is returned only if 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/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 gets a list of files and folders in the bucket. Files are output in the Contents elements, and folders in the CommonPrefixes elements.

If the request also specifies the prefix parameter, Object Storage returns 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 leaves the keys starting from the one following the marker.
max-keys Maximum number of elements in a response.

By default, Object Storage returns a maximum of 1000 Contents and CommonPrefixes elements. This parameter should be used if you need to get less than 1000 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 their number exceeds 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 NextMarker element from the previous response.
prefix String to start the key from.

Object Storage selects only those keys that start with prefix.

Can be used simultaneously with the delimiter parameter. In this case, the output logic is determined by the delimiter parameter.

Headers

Use only common request headers in requests.

Response

Headers

Responses 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>
   <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 indicating whether all results are returned in the response.

True: All.False: Not 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 or COLD.

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 Part of the key name that is identified when processing the delimiter and prefix query parameters.

Path: /ListBucketResult/CommonPrefixes.
EncodingType Encoding in which Object Storage provides a key in the XML response.

Appears if the client passed the encoding-type parameter in the request.

Path: /ListBucketResult/EncodingType.
In this article:
  • listObjectsV2
  • Request
  • Response
  • listObjectsV1
  • Request
  • Response
Language
Careers
Privacy policy
Terms of use
© 2021 Yandex.Cloud LLC