Call GetBucketV2 to list objects in a bucket - Object Storage Service

The ListObjectsV2 (GetBucketV2) operation lists the objects in a bucket.

Usage notes

To list all objects in a bucket, you must have the oss:ListObjects permission.
The ListObjectsV2 (GetBucketV2) request does not return custom object metadata.
If you enable log storage or real-time log query, the value of the operation field in the access logs generated for this operation is GetBucket.
Calls to the ListObjectsV2 (GetBucketV2) operation are billed as PUT requests. For more information, see PUT requests.
By default, a single response returns a maximum of 100 objects. To retrieve all objects, you must retrieve them in segments using parameters such as `NextContinuationToken` and `continuationToken`.
If versioning is enabled for a bucket, overwrite or accidental delete operations create many delete markers and previous versions. Configure a lifecycle rule to periodically clean up delete markers and unneeded previous versions to prevent a decrease in list performance.

Request syntax

GET /?list-type=2 HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request parameters

Name	Type	Required	Example	Description
list-type	Number	Yes	2	The value can only be 2.
delimiter	String	No	/	A character for grouping object names. All object names that contain the specified prefix and appear before the first occurrence of the delimiter are grouped as an element (CommonPrefixes). Default value: none
start-after	String	No	b	Specifies that the list of objects is returned starting from the object that alphabetically follows the `start-after` value. `start-after` is used for pagination. The parameter must be less than 1024 bytes in length. For a conditional query, even if the `start-after` value does not exist in the list, the response starts from the next object that follows the `start-after` value in alphabetical order. Default value: none
continuation-token	String	No	test1.txt	Specifies that the list operation starts from this token. You can obtain this token from the `NextContinuationToken` value in the response of a ListObjectsV2 (GetBucketV2) operation.
max-keys	String	No	100	Specifies the maximum number of objects to return. Value: an integer from 1 to 1000 Default value: 100 Note If not all objects can be listed in a single response due to the `max-keys` setting, the response includes `NextContinuationToken`. Use this token as the `continuation-token` for the next request. The number of returned objects is not guaranteed to reach the specified `max-keys` value. If this occurs, get the `NextContinuationToken` from the response and use it as the `continuation-token` for the next request.
prefix	String	No	a	Limits the response to keys that begin with the specified prefix. If you set `prefix` to a folder name, the operation lists all files and subfolders that start with this prefix. If you set `prefix` and also set `delimiter` to a forward slash (/), the response lists only the files in that folder. The names of subfolders are returned in `CommonPrefixes`, and the files and folders within those subfolders are not listed. For example, a bucket contains three objects: `fun/test.jpg`, `fun/movie/001.avi`, and `fun/movie/007.avi`. If you set `prefix` to `fun/`, all three objects are returned. If you set `prefix` to `fun/` and `delimiter` to `/`, `fun/test.jpg` and `fun/movie/` are returned. Note The parameter must be less than 1024 bytes in length. The `prefix` parameter cannot start with a forward slash (/). If the `prefix` parameter is empty, all objects in the bucket are listed by default. When you query using `prefix`, the returned keys still include the prefix. Default value: none
encoding-type	String	No	url	Encodes the response and specifies the encoding type. Default value: none Valid value: url Note `delimiter`, `start-after`, `prefix`, `NextContinuationToken`, and `Key` use UTF-8 characters. If these parameters contain control characters that are not supported by XML 1.0, you can specify `encoding-type` to encode the `delimiter`, `start-after`, `prefix`, `NextContinuationToken`, and `Key` elements in the response.
fetch-owner	Boolean	No	false	Specifies whether to include owner information in the response. Valid values: true, false true: The response includes owner information. false: The response does not include owner information. Default value: false

Response elements

Name	Type	Example	Description
Contents	Container	N/A	A container for the metadata of each returned object. Parent node: ListBucketResult
CommonPrefixes	Container	N/A	If the request specifies the `Delimiter` parameter, the response includes the `CommonPrefixes` element. This element indicates a collection of object names that end with the delimiter and share a common prefix. Parent node: ListBucketResult Child node: Prefix
Delimiter	String	/	The character used to group object names. All object names that contain the specified prefix and appear before the first occurrence of the delimiter are grouped as a `CommonPrefixes` element. Parent node: ListBucketResult
EncodingType	String	N/A	The encoding type used in the response. If `encoding-type` is specified in the request, the `Delimiter`, `StartAfter`, `Prefix`, `NextContinuationToken`, and `Key` elements in the response are encoded. Parent node: ListBucketResult
DisplayName	String	user_example	The name of the object owner. Parent node: ListBucketResult.Contents.Owner
ETag	String	5B3C1A2E053D763E1B002CC607C5A0FE1****	The ETag is created when an object is generated and identifies the content of the object. Parent node: ListBucketResult.Contents For an object created by a PutObject request, the ETag is the MD5 hash of its content. For an object created in other ways, the ETag is a unique value generated based on a specific calculation rule, but it is not the MD5 hash of its content. The ETag can be used to check if the object content has changed. Do not use the ETag as the basis for MD5 validation to ensure data integrity.
ID	String	0022012****	The user ID of the bucket owner. Parent node: ListBucketResult.Contents.Owner
IsTruncated	Enumerated string	false	Indicates whether the returned results are truncated. Return values: true, false true indicates that not all results are returned. false indicates that all results are returned. Parent node: ListBucketResult
Key	String	fun/test.jpg	The key of the object. Parent node: ListBucketResult.Contents
LastModified	Time	2012-02-24T08:42:32.000Z	The time when the object was last modified. Parent node: ListBucketResult.Contents
ListBucketResult	Container	N/A	A container for the results of the GetBucket request. Child nodes: Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, Contents Parent node: None
StartAfter	String	test1.txt	If the request specifies the `StartAfter` parameter, the response includes the `StartAfter` element.
MaxKeys	String	100	The maximum number of results returned in the response. Parent node: ListBucketResult
Name	String	examplebucket	The name of the bucket. Parent node: ListBucketResult
Owner	Container	N/A	A container for the bucket owner's information. Child nodes: DisplayName, ID Parent node: ListBucketResult.Contents
Prefix	String	fun/	The prefix of the query results. Parent node: ListBucketResult
Type	String	Normal	File type Valid values: Normal, Multipart, Appendable, and Symlink. Parent node: ListBucketResult.Contents
Size	String	344606	The size of the object in bytes. Parent node: ListBucketResult.Contents
StorageClass	String	Standard	The storage class of the object. Parent node: ListBucketResult.Contents
SealedTime	Time	2020-05-21T12:07:15.000Z	The time when the Seal operation was performed on the object. This field is returned when you access an Appendable Object that is in the Sealed state. Parent node: ListBucketResult.Contents
ContinuationToken	String	test1.txt	If the request specifies the `ContinuationToken` parameter, the response includes the `ContinuationToken` element. Parent node: ListBucketResult
KeyCount	Number	6	The number of keys returned in this request. If `Delimiter` is specified, `KeyCount` is the sum of the number of `Key` and `CommonPrefixes` elements. Parent node: ListBucketResult
NextContinuationToken	String	CgJiYw--	Indicates that the ListObjectsV2 (GetBucketV2) request has more results. To get the next set of results, specify `NextContinuationToken` as the `ContinuationToken`. Parent node: ListBucketResult
RestoreInfo	String	ongoing-request="true"	The restored state of the object. If no RestoreObject requests are sent or the requests expire, this element is not included in the response. If a RestoreObject request is sent but the restoration is not complete, the value of the RestoreInfo element is `ongoing-request="true"`. If a RestoreObject request is sent and the restoration is complete, the value of the RestoreInfo element is in the `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"` format, in which the `expiry-date` element indicates the time before which the restored object can be read. Parent node: ListBucketResult.Contents

Examples

Sample request

GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1866
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>examplebucket</Name>
    <Prefix></Prefix>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b</Key>
        <LastModified>2020-05-18T05:45:50.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>c</Key>
        <LastModified>2020-05-18T05:45:57.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>6</KeyCount>
</ListBucketResult>

Sample request that uses the prefix parameter

GET /?list-type=2&prefix=a HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1464
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>examplebucket</Name>
    <Prefix>a</Prefix>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>2</KeyCount>
</ListBucketResult>

Sample request that uses the prefix and delimiter parameters

GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 712
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>examplebucket</Name>
    <Prefix>a/</Prefix>
    <MaxKeys>100</MaxKeys>
    <Delimiter>/</Delimiter>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>a/b/</Prefix>
    </CommonPrefixes>
    <KeyCount>2</KeyCount>
</ListBucketResult>

Sample request that uses the start-after, max-keys, and fetch-owner parameters

GET /?list-type=2&start-after=b&max-keys=3&fetch-owner=true HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 712
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>examplebucket</Name>
    <Prefix></Prefix>
    <StartAfter>b</StartAfter>
    <MaxKeys>3</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>CgJiYw--</NextContinuationToken>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>ba</Key>
        <LastModified>2020-05-18T11:17:58.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <KeyCount>3</KeyCount>
</ListBucketResult>

Sample request that lists all objects in a bucket, including Archive or Cold Archive objects

In this example, the examplebucket bucket contains the following Cold Archive objects: exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt. The three objects are in the following states:

No RestoreObject requests are sent to restore exampleobject1.txt or the RestoreObject requests sent to restore the object have expired.
A RestoreObject request is sent to restore exampleobject2.txt and the object is being restored.
A RestoreObject request is sent to restore exampleobject3.txt and the object is restored.

Sample requests

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample success responses

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1866
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
  <Name>examplebucket</Name>
  <Prefix></Prefix>
  <Marker></Marker>
  <MaxKeys></MaxKeys>
  <Delimiter></Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
        <Key>exampleobject1.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>ColdArchive</StorageClass>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
  <Contents>
        <Key>exampleobject2.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="true"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
  <Contents>
        <Key>exampleobject3.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
</ListBucketResult>

SDK

This operation is available in the following SDKs:

ossutil command line interface

For more information about the ossutil command for the ListObjectsV2 operation, see list-objects-v2 (get-bucket-v2).

Error code	HTTP status code	Description
NoSuchBucket	404	The requested bucket does not exist. Check whether the name of the requested bucket complies with the naming rules.
AccessDenied	403	You do not have the permissions to access the bucket. Only the bucket owner and RAM users who are granted the `oss:ListObjects` permission can access the bucket.
InvalidArgument	400	The value of max-keys is less than 0 or greater than 1,000. The length of the value of prefix, marker, or delimiter is invalid.