[Yandex Cloud documentation](../../../../index.md) > [Yandex Object Storage](../../../index.md) > API reference > [AWS S3 REST](../../index.md) > [REST](../index.md) > Bucket > ListObjects

# Object Storage API, Amazon S3-compatible REST: ListObjects

Returns a list of bucket objects.

It does not return object contents; use the [get](../object/get.md) 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 info %}

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`](#requestV2) parameter.

{% endnote %}

For more information on getting started with the API and the general request format, see [How to use the S3 API](../../index.md).

## listObjectsV2 {#listObjectsV2}

### Request {#requestV2}

```http
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 {#path-parametersV2}

Parameter | Description
----- | -----
`bucket` | Bucket name.

#### Query parameters {#parametersV2}

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.<br/>To get the next part of the list, use the `NextContinuationToken` value from the previous response.
`delimiter` | Delimiter character.<br/><br/>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 <q>files</q> and <q>folders</q> in the bucket. <q>Files</q> will be output in the `Contents` elements, and <q>folders</q> in the `CommonPrefixes` elements.<br/><br/>If the request also specifies the `prefix` parameter, Object Storage will return a list of <q>files</q> and <q>folders</q> in the `prefix` <q>folder</q>.
`encoding-type` | Encoding of server responses.<br/><br/>Object Storage can encode responses in the format requested by the client.<br/><br/>Possible values: `url`.
`max-keys` | Maximum number of elements per response.<br/><br/>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.<br/><br/>If the selection criteria are met by more keys than the output has room for, the response contains `<IsTruncated>true</IsTruncated>`.<br/><br/>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.<br/><br/>Object Storage will select only keys that start with `prefix`.<br/><br/>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 {#request-headersV2}
Use only [common headers](../common-request-headers.md) in your requests.

### Response {#responseV2}

#### Headers {#response-headersV2}

Responses can only contain [common headers](../common-response-headers.md).

#### Response codes {#response-codesV2}

For a list of possible responses, see [Responses](../response-codes.md).

A successful response contains additional data in XML format with the schema described below.

#### Data schema {#structureV2}

```xml
<?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.<br/><br/>`True` for not all, `False` for all.<br/><br/>Path: `/ListBucketResult/IsTruncated`.
`Contents` | Object description.<br/><br/>The response will contain as many `Contents` elements as there are keys that meet the request criteria.<br/><br/>Path: `/ListBucketResult/Contents`.
`ETag` | MD5 hash of the object. No metadata is included in the hash value calculation.<br/><br/>Path: `/ListBucketResult/Contents/ETag`.
`Key` | Object key.<br/><br/>Path: `/ListBucketResult/Contents/Key`.
`LastModified` | Date and time when the object was last modified.<br/><br/>Path: `/ListBucketResult/Contents/LastModified`.
`Size` | Object size in bytes.<br/><br/>Path: `/ListBucketResult/Contents/Size`.
`StorageClass` | Object [storage class](../../../concepts/storage-class.md): `STANDARD`, `COLD`, `ICE`, or `INTELLIGENT_TIERING`.<br/><br/>Path: `/ListBucketResult/Contents/StorageClass`.
`Name` | Bucket name.<br/><br/>Path: `/ListBucketResult/Name`.
`Prefix` | Value of the `prefix` query parameter.<br/><br/>Path: `/ListBucketResult/Prefix`.
`Delimiter` | Value of the `delimiter` query parameter.<br/><br/>Path: `/ListBucketResult/Delimiter`.
`MaxKeys` | Value of the `max-keys` query parameter.<br/><br/>Path: `/ListBucketResult/MaxKeys`.
`CommonPrefixes` | Key name part identified when processing the `delimiter` and `prefix` query parameters.<br/><br/>Path: `/ListBucketResult/CommonPrefixes`.
`EncodingType` | Encoding used by Object Storage to provide a key in an XML response.<br/><br/>You will get this tag if the client provided the `encoding-type` parameter in the request.<br/><br/>Path: `/ListBucketResult/EncodingType`.
`KeyCount` | Number of keys returned by the request.<br/>The number of keys is always less than or equal to `MaxKeys`.<br/><br/>Path: `/ContinuationToken/KeyCount`.
`ContinuationToken` | Value of the `continuation-token` query parameter.<br/><br/>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.<br/>It is returned only when `IsTruncated = true`.<br/><br/>Path: `/ListBucketResult/NextContinuationToken`.
`StartAfter` | Value of the `start-after` query parameter.<br/><br/>Path: `/ListBucketResult/StartAfter`.

## listObjectsV1 {#listObjectsV1}

### Request {#requestV1}

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

#### Path parameters {#path-parametersV1}

Parameter | Description
----- | -----
`bucket` | Bucket name.

#### Query parameters {#parametersV1}

All parameters listed in the table are optional.

Parameter | Description
----- | -----
`delimiter` | Delimiter character.<br/><br/>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 <q>files</q> and <q>folders</q> in the bucket. <q>Files</q> will be output in the `Contents` elements, and <q>folders</q> in the `CommonPrefixes` elements.<br/><br/>If the request also specifies the `prefix` parameter, Object Storage will return a list of <q>files</q> and <q>folders</q> in the `prefix` <q>folder</q>.
`encoding-type` | Encoding of server responses.<br/><br/>Object Storage can encode responses in the format requested by the client.<br/><br/>Possible values: `url`.
`marker` | Key the output starts from.<br/><br/>In the output, Object Storage will leave the keys starting from the one that follows `marker`.
`max-keys` | Maximum number of elements per response.<br/><br/>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.<br/><br/>If the selection criteria are met by more keys than the output has room for, the response contains `<IsTruncated>true</IsTruncated>`.<br/><br/>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.<br/><br/>Object Storage will select only keys that start with `prefix`.<br/><br/>Can be used at the same time with the `delimiter` parameter. In this case, the output logic is determined by the `delimiter` parameter.

#### Headers {#request-headersV1}
Use only [common headers](../common-request-headers.md) in your requests.

### Response {#responseV1}

#### Headers {#response-headersV1}

Responses can only contain [common headers](../common-response-headers.md).

#### Response codes {#response-codesV1}

For a list of possible responses, see [Responses](../response-codes.md).

A successful response contains additional data in XML format with the schema described below.

#### Data schema {#structureV1}

```xml
<?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.<br/><br/>`True` stands for not all, `False` stands for all.<br/><br/>Path: `/ListBucketResult/IsTruncated`.
`Marker` | Value of the `marker` query parameter.<br/><br/>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.<br/><br/>Path: `/ListBucketResult/NextMarker`.
`Contents` | Object description.<br/><br/>The response will contain as many `Contents` elements as there are keys that meet the request criteria.<br/><br/>Path: `/ListBucketResult/Contents`.
`ETag` | MD5 hash of the object. No metadata is included in the hash value calculation.<br/><br/>Path: `/ListBucketResult/Contents/ETag`.
`Key` | Object key.<br/><br/>Path: `/ListBucketResult/Contents/Key`.
`LastModified` | Date and time when the object was last modified.<br/><br/>Path: `/ListBucketResult/Contents/LastModified`.
`Size` | Object size in bytes.<br/><br/>Path: `/ListBucketResult/Contents/Size`.
`StorageClass` | Object [storage class](../../../concepts/storage-class.md): `STANDARD`, `COLD`, `ICE`, or `INTELLIGENT_TIERING`.<br/><br/>Path: `/ListBucketResult/Contents/StorageClass`.
`Name` | Bucket name.<br/><br/>Path: `/ListBucketResult/Name`.
`Prefix` | Value of the `prefix` query parameter.<br/><br/>Path: `/ListBucketResult/Prefix`.
`Delimiter` | Value of the `delimiter` query parameter.<br/><br/>Path: `/ListBucketResult/Delimiter`.
`MaxKeys` | Value of the `max-keys` query parameter.<br/><br/>Path: `/ListBucketResult/MaxKeys`.
`CommonPrefixes` | Key name part identified when processing the `delimiter` and `prefix` query parameters.<br/><br/>Path: `/ListBucketResult/CommonPrefixes`.
`EncodingType` | Encoding used by Object Storage to provide a key in an XML response.<br/><br/>You will get this tag if the client provided the `encoding-type` parameter in the request.<br/><br/>Path: `/ListBucketResult/EncodingType`.

#### Related articles {#related-articles}

* [Bucket in Object Storage](../../../concepts/bucket.md)

* [Get a list of bucket objects](../../../operations/objects/list.md)

#### Useful links {#see-also}

* [Getting started with the AWS S3 API in Yandex Object Storage](../../s3-api-quickstart.md)

* [Debugging requests using the AWS CLI](../../signing-requests.md#debugging)

* [Example of sending a signed request using curl](../../../api-ref/authentication.md#s3-api-example)

* [Code example for generating a signature](../../../concepts/pre-signed-urls.md#code-examples)