Queries the information about all objects in a bucket.

Note The user metadata of objects is not returned for GetBucketV2 (ListObjectsV2) requests.

Request syntax

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

Request parameters

Parameter Type Required Example Description
list-type Number Yes 2 The version of the GetBucket (ListObjects) operation. Set the value to 2.
delimiter String No / The character that is used to group objects by name. If you specify the delimiter parameter in the request, the response contains the CommonPrefixes element. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

This parameter is empty by default.
start-after String No b The name of the object after which the list begins. The names of objects are returned in alphabetical order.

The start-after parameter is used to list the returned objects by page. The parameter value must be less than 1,024 bytes in length.

Even if the specified start-after does not exist during a conditional query, the list starts from the object whose name is alphabetically greater than the start-after value.

This parameter is empty by default.
continuation-token String No test1.txt The token from which the list operation must start. You can obtain the token from NextContinuationToken in the GetBucketV2 (ListObjectsV2) response.
max-keys String No 100 The maximum number of objects to return.

Valid values: 1 to 1000

Default value: 100

Note If the number of objects exceeds the max-keys value, the response includes <NextContinuationToken> as the continuation token for the next list operation.
prefix String No a The prefix that the returned object names must contain.

If prefix is set to a directory name in the request, the objects whose names contain this prefix are listed, including all objects and subdirectories in the directory.

If you specify prefix and set delimiter to a forward slash (/), only the objects in the directory are listed. The subdirectories are grouped together as a single result in CommonPrefixes. However, objects and directories in the subdirectories are not listed.

For example, a bucket contains the following three objects: fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. If prefix is set to fun/, the three objects are returned. If prefix is set to fun/ and delimiter is set to a forward slash (/), fun/test.jpg and fun/movie/ are returned.

Note
  • The prefix value must be less than 1,024 bytes in length.
  • If you specify a prefix to query objects, the returned object names contain the prefix.

This parameter is empty by default.
Encoding-type String No url The encoding type of the content in the response.

This parameter is empty by default.

Valid value: url

Note The delimiter, start-after, prefix, NextContinuationToken, and Key values are UTF-8 encoded. If the delimiter, start-after, prefix, NextContinuationToken, or Key value contains control characters that are not supported by the XML 1.0 standard, you can specify encoding-type to encode the value in the response.
Fetch-owner Boolean No false Specifies whether to include the owner information in the response.

Valid values: true and false

  • true: The response includes the owner information.
  • false: The response does not include the owner information.

Default value: false

Response elements

Element Type Example Description
Contents Container N/A The container that stores the returned object metadata.

Parent nodes: ListBucketResult
CommonPrefixes String N/A If the Delimiter parameter is specified in the request, the response contains the CommonPrefixes element. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

Parent nodes: ListBucketResult
Delimiter String / The character that is used to group objects by name. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes.

Parent nodes: ListBucketResult
EncodingType String N/A The encoding type of the content in the response. If you specify Encoding-type in the request, the values of Delimiter, StartAfter, Prefix, NextContinuationToken, and Key are encoded in the response.

Parent nodes: ListBucketResult
DisplayName String user_example The name of the object owner.

Parent nodes: ListBucketResult.Contents.Owner
ETag String 5B3C1A2E053D763E1B002CC607C5A0FE1**** The entity tag (ETag). An ETag is created when an object is created to identify the content of the object.

Parent nodes: ListBucketResult.Contents

  • If an object is created by calling the PutObject operation, the ETag value of the object is the MD5 hash of the object content.
  • If an object is created by using another method, the ETag value is not the MD5 hash of the object content but a unique value calculated based on a specific rule.
  • The ETag value of an object can be used to check whether the object content is modified. However, we recommend that you use the MD5 hash of an object rather than the ETag of the object to verify data integrity.
ID String 0022012**** The user ID of the bucket owner.

Parent nodes: ListBucketResult.Contents.Owner
IsTruncated Enumerated string false Indicates whether the returned results are truncated.
Valid values: true and false
  • true indicates that not all of the results are returned this time.
  • false indicates that all of the results are returned this time.

Parent nodes: ListBucketResult
Key String fun/test.jpg The name of the object.

Parent nodes: ListBucketResult.Contents
LastModified Time 2012-02-24T08:42:32.000Z The last modified time of the object.

Parent nodes: ListBucketResult.Contents
ListBucketResult Container N/A The container that stores the result of the GetBucket request.

Child nodes: Name, Prefix, StartAfter, MaxKeys, Delimiter, IsTruncated, NextContinuationToken, and Contents

Parent nodes: none
StartAfter String test1.txt If the StartAfter parameter is specified in the request, the response contains the StartAfter element.
MaxKeys String 100 The maximum number of returned objects in the response.

Parent nodes: ListBucketResult
Name String examplebucket The name of the bucket.

Parent nodes: ListBucketResult
Owner Container N/A The container that stores the information about the bucket owner.

Child nodes: DisplayName and ID

Parent nodes: Contents
Prefix String fun/ The prefix contained in the returned object names.

Parent nodes: ListBucketResult
Size String 344606 The size of the returned object. Unit: bytes.

Parent nodes: ListBucketResult.Contents
StorageClass String Standard The storage class of the object.

Parent nodes: ListBucketResult.Contents
ContinuationToken String test1.txt If the ContinuationToken parameter is specified in the request, the response contains the ContinuationToken element.
KeyCount Number 6 The number of object names returned for this request. If Delimiter is specified, the KeyCount value is the sum of the Key and CommonPrefixes values.
NextContinuationToken String CgJiYw-- The name of the object from which the next list operation starts. The NextContinuationToken value is used as the ContinuationToken value to query subsequent results.
RestoreInfo String ongoing-request="true" The restoration status of the object.
  • If no RestoreObject requests are sent or the requests expire, this field is not included in the response.
  • If a RestoreObject request is sent and the object is still being restored, the returned RestoreInfo value is ongoing-request="true".
  • If a RestoreObject request is sent and the object is restored, the returned RestoreInfo value is in the following format: ongoing-request="false”, expiry-date="Thr, 24 Mon 2020 12:40:33 GMT". In this returned RestoreInfo value, the expiry-date field indicates the time before which the restored object can be read.

Examples

  • Sample requests for simple GetBucketV2 (ListObjectsV2) operations 
    GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykbo****
    Sample responses 
    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 requests that have the Prefix parameter specified 
    GET /?list-type=2&prefix=a HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykbo****
    Sample responses 
    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 requests that have the Prefix and Delimiter parameters specified 
    GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY****
    Sample responses 
    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 requests that have the StartAfter, MaxKeys, and FetchOwner parameters specified 
    GET /?list-type=2&start-after=b&max=keys=3&fetch-owner=true HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY****
    Sample responses 
    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 requests that are sent to list all objects including Archive or Cold Archive objects in a bucket
    In this example,the examplebucket bucket contains the following three Cold Archive objects: exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt. The three objects are in the following different states:
    • No RestoreObject requests are sent to restore exampleobject1.txt or the RestoreObject requests sent to restore the object expire.
    • A RestoreObject request is sent to restore exampleobject2.txt. The object is still 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: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykbo****

    Sample 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="Thr, 24 Mon 2020 12:40:33 GMT"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
</ListBucketResult>
Error code HTTP status code Description
NoSuchBucket 404 The error message returned because the requested bucket does not exist. Check whether the name of the requested bucket complies with the naming rules.
AccessDenied 403 The error message returned because you are not authorized 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 error message returned because the max-keys value is less than 0 or greater than 1,000.
  • The error message returned because the length of the prefix, marker, or delimiter value is invalid.