ListObjectsV2 GetBucketV2 - list bucket objects OSS API - Object Storage Service

Notes

To list all objects in a bucket, you must have the oss:ListObjects permission.
The ListObjectsV2 (GetBucketV2) operation does not return custom object metadata.
If log storage or real-time log query is enabled, this operation is logged as GetBucket.
The ListObjectsV2 (GetBucketV2) operation is billed as a PUT API request.
A single response returns up to 100 objects by default. Use NextContinuationToken and continuation-token to paginate through all results.
If versioning is enabled, overwriting or deleting objects can accumulate delete markers and previous versions. Configure lifecycle rules to periodically clean up delete markers and unnecessary previous versions to maintain 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 operation version. Set to 2.
delimiter	String	No	/	The character used to group object keys. Keys that share a common prefix up to the first occurrence of the delimiter are grouped into a single CommonPrefixes entry. Default value: None
start-after	String	No	b	The object key after which the listing begins. Results start from the first key alphabetically after this value. Use for pagination. Maximum length: 1,024 bytes. If the specified start-after value does not exist, the listing starts from the next key in alphabetical order. Default value: None
continuation-token	String	No	test1.txt	The token from which the listing starts. Obtain this value from NextContinuationToken in a previous ListObjectsV2 (GetBucketV2) response.
max-keys	String	No	100	The maximum number of objects to return. Valid values: 1 to 1000 Default value: 100 Note If the response is truncated due to max-keys, use the returned `NextContinuationToken` as the `continuation-token` for the next request. The actual number of returned objects may be less than max-keys. If so, use `NextContinuationToken` from the response as `continuation-token` for the next request.
prefix	String	No	a	The prefix that returned object keys must contain. If set to a folder name, all files and subfolders with this prefix are listed recursively. If prefix is set and delimiter is set to /, only files in the folder are listed. Subfolder names appear in CommonPrefixes without recursive listing. Example: a bucket contains fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. Setting prefix to fun/ returns all three. Setting prefix to fun/ with delimiter / returns fun/test.jpg and fun/movie/. Note Maximum length: 1,024 bytes. The prefix cannot start with a forward slash (/). If left empty, all objects in the bucket are listed. Returned keys still contain the prefix. Default value: None
encoding-type	String	No	url	The encoding type for the response. Default value: None Valid value: url Note If delimiter, start-after, prefix, NextContinuationToken, or Key values contain control characters not supported by XML 1.0, specify encoding-type to encode them in the response.
fetch-owner	Boolean	No	false	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 Delimiter parameter is specified, the response includes CommonPrefixes, which lists object name prefixes that share a common prefix and end with the delimiter. Parent node: ListBucketResult Child node: Prefix
Delimiter	String	/	The character used to group object keys. Keys sharing a common prefix up to the first delimiter occurrence are grouped into a single CommonPrefixes entry. Parent node: ListBucketResult
EncodingType	String	N/A	The encoding type used in the response. If Encoding-type is specified in the request, Delimiter, StartAfter, Prefix, NextContinuationToken, and Key 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 identifies the content of an object, generated when the object is created. Parent node: ListBucketResult.Contents For objects created by a PutObject request, the ETag value is the MD5 hash of the object content. For objects created by other methods, the ETag value is a unique value calculated based on a specific rule, but it is not the MD5 hash of the object content. The ETag can check whether object content has changed, but is not suitable for data integrity verification. Use MD5 hash instead.
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. Valid values: true, false true: Not all results are returned this time. false: All results are returned this time. 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 last modified time of the object. Parent node: ListBucketResult.Contents
ListBucketResult	Container	N/A	The container for the results of a GetBucket request. Child nodes: Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, Contents Parent node: None
StartAfter	String	test1.txt	If you specify the StartAfter parameter in the request, 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 information about the bucket owner. Child nodes: DisplayName, ID Parent node: ListBucketResult.Contents
Prefix	String	fun/	The prefix of the query results. Parent node: ListBucketResult
Type	String	Normal	The object type. Valid values: Normal, Multipart, Appendable, 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 object was sealed. Returned only for sealed appendable objects. Parent node: ListBucketResult.Contents
ContinuationToken	String	test1.txt	If you specify the ContinuationToken parameter in the request, the response includes the ContinuationToken element. Parent node: ListBucketResult
KeyCount	Number	6	The number of keys returned. If Delimiter is specified, KeyCount is the sum of Key and CommonPrefixes elements. Parent node: ListBucketResult
NextContinuationToken	String	CgJiYw--	The token for retrieving the next page of results. Use this value as continuation-token in the next ListObjectsV2 (GetBucketV2) request. Parent node: ListBucketResult
RestoreInfo	String	ongoing-request="true"	The restored state of the object. Not returned if no RestoreObject request is submitted, or if the RestoreObject request has expired. If a RestoreObject request is submitted but the restore operation is not complete, the value of RestoreInfo is `ongoing-request="true"`. If a RestoreObject request is submitted and the restore operation is complete, the value of RestoreInfo is `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`. The `expiry-date` field indicates the expiration time of the restored object. Parent node: ListBucketResult.Contents

Examples

Simple 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>

Request with 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>

Request with 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>

Send a request with 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>

Request for a bucket that contains Archive or Cold Archive objects

Assume that the examplebucket bucket contains the exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt objects. All three objects are in the Cold Archive storage class. The states of the three objects are as follows:

For exampleobject1.txt, a RestoreObject request has not been submitted, or the submitted RestoreObject request has expired.
For exampleobject2.txt, a RestoreObject request has been submitted, and the restore operation is in progress.
For exampleobject3.txt, a RestoreObject request has been submitted and the restore operation is complete.

Sample request

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 response

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

SDKs for this operation:

ossutil command-line tool

The corresponding ossutil command is list-objects-v2 (get-bucket-v2).

Error code	HTTP status code	Description
NoSuchBucket	404	The specified bucket does not exist. Check whether the bucket name is valid.
AccessDenied	403	You lack the required permissions. Only the bucket owner or users granted the `oss:ListObjects` permission can perform this operation.
InvalidArgument	400	The value of max-keys is less than 0 or greater than 1,000. The length of the prefix, marker, or delimiter parameter is invalid.