List objects by calling GetBucket (ListObjects) - Object Storage Service

Lists information about all objects in an Object Storage Service (OSS) bucket.

Notes

The GetBucket (ListObjects) operation has been revised to GetBucketV2 (ListObjectsV2). We recommend that you use the newer version GetBucketV2 (ListObjectsV2) when you develop applications. To ensure backward compatibility, OSS continues to support GetBucket (ListObjects). For more information about GetBucketV2 (ListObjectsV2), see ListObjectsV2 (GetBucketV2).
When you call the GetBucket (ListObjects) operation, the custom metadata of objects is not returned.
GetBucket (ListObjects) is a bucket-level operation. You are charged an API calling fee each time you call the GetBucket (ListObjects) operation. For more information, see API Request.
After versioning is enabled for a bucket, overwrite or delete operations generate many delete markers and historical versions. We recommend that you configure lifecycle rules to periodically clean up delete markers and historical versions that are no longer needed to avoid impacts on the list performance.

Request syntax

GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

This operation involves only common request headers such as Authorization and Host. For more information, see Common Request Headers.

Request parameters

Name	Type	Required	Example	Description
delimiter	string	No	/	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. By default, this field is empty.
marker	string	No	test1.txt	The name of the object after which the list operation starts. If this parameter is specified, objects whose names are alphabetically after the marker value are returned. The marker parameter is used to list the returned objects by page, and the value of marker must be smaller than 1,024 bytes in length. Even if the specified marker does not exist in the list during a conditional query, the list starts from the object whose name is alphabetically after the value of the marker parameter. By default, this field is empty.
max-keys	string	No	200	The maximum number of objects that you want to return. If the list operation cannot be complete at a time because max-keys is specified, the NextMarker element is included in the response as the marker for the next list operation. Valid values: 1 to 1000 Default value: 100
prefix	string	No	fun	The prefix that the names of the returned objects must contain. The prefix value must be smaller than 1,024 bytes in length. If you specify a prefix, the names of the returned objects still contain the prefix. 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 prefix is specified and delimiter is set to a forward slash (/), only objects in the directory are listed. The names of the subdirectories in the directory are returned in the CommonPrefixes element. 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. By default, this field is empty.
encoding-type	string	No	url	The encoding type of the object names in the response. By default, this field is empty. Valid value: url Important The delimiter, marker, prefix, NextMarker, and Key values are UTF-8 encoded. If the value of delimiter, marker, prefix, NextMarker, or Key contains a control character that is not supported by the XML 1.0 standard, you can specify encoding-type to encode the value in the response.

Response elements

Name	Type	Example	Description
ListBucketResult	container	N/A	The container that stores the result of the GetBucket request. Child nodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, NextMarker, and Contents Parent nodes: none
Name	string	oss-example	The name of the bucket. Parent nodes: ListBucketResult
Prefix	string	fun/	The prefix contained in the names of returned objects. Parent nodes: ListBucketResult or CommonPrefixes
Marker	string	test1.txt	The name of the object after which the list operation begins. Parent nodes: ListBucketResult
MaxKeys	string	100	The maximum number of returned objects in the response. Parent nodes: ListBucketResult
Delimiter	string	/	The character 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	url	The encoding type of the object name in the response. If you specify the encoding-type parameter in the request, the following elements in the response are encoded: Delimiter, Marker, Prefix, NextMarker, and Key. Parent nodes: ListBucketResult
IsTruncated	enumerated string	false	Indicates whether the returned list is truncated. Valid values: true and false true indicates that not all results are returned this time. false indicates that all results are returned this time. Parent nodes: ListBucketResult
NextMarker	string	test100.txt	The position from which the next list operation starts. Parent nodes: ListBucketResult
Contents	container	N/A	The container that stores the metadata of each returned object. Parent nodes: ListBucketResult
Key	string	fun/test.jpg	The name of the object. Parent nodes: ListBucketResult.Contents
TransitionTime	time	2024-04-23T07:21:42.000Z	The time when the storage class of the object is converted to Cold Archive or Deep Cold Archive based on lifecycle rules. Note If the object is stored for more than 180 days after the storage class of the object is converted, you are not charged for the storage usage of the Cold Archive or Deep Cold Archive object that is stored for less than the minimum storage duration. If the object is stored for less than 180 days after the storage class of the object is converted, you are charged for the storage usage of the Cold Archive or Deep Cold Archive object that is stored for less than the minimum storage duration. You cannot use this header to query the time when the storage class of the object is converted to Infrequent Access (IA) or Archive based on lifecycle rules. You can determine whether the object is stored for more than the minimum storage duration based on the value of the `Last-Modified` header. Parent nodes: ListBucketResult.Contents
LastModified	time	2012-02-24T08:42:32.000Z	The time when the object was last modified. Note The minimum storage duration (30 days) of IA objects is calculated based on the last modified time of the objects. If the value of the Last-Modified header is 30 days earlier than the current time, you are not charged for the storage usage of the IA object that is stored for less than the minimum storage duration. The minimum storage duration (60 days) of Archive objects is calculated based on the last modified time of the objects. If the value of the Last-Modified header is 60 days earlier than the current time, you are not charged for the storage usage of the Archive object that is stored for less than the minimum storage duration. Parent nodes: ListBucketResult.Contents
ETag	string	5B3C1A2E053D763E1B002CC607C5A0FE1****	The entity tag (ETag). An ETag is created when an object is created to identify the content of the object. 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 changes. However, we recommend that you use the MD5 hash of an object rather than the ETag value of the object to verify data integrity. Parent nodes: ListBucketResult.Contents
Type	string	Normal	The type of the object. The following four types are available: Normal: The object is uploaded by using simple upload. Multipart: The object is uploaded by using multipart upload. Appendable: The object is uploaded by using append upload. Symlink: The symbolic link created by using the PutSymlink operation.
Size	string	344606	The size of the object. Unit: bytes. Parent nodes: ListBucketResult.Contents
StorageClass	string	Standard	The storage class of the object. Parent nodes: ListBucketResult.Contents
RestoreInfo	string	ongoing-request="true"	The restoration status of the object. If the RestoreObject request is not submitted or the RestoreObject request has expired, this field is not returned. If the RestoreObject request has been submitted, but the restore operation is not complete, the returned RestoreInfo value is `ongoing-request="true"`. If a RestoreObject request has been submitted and the restore operation is complete, the returned RestoreInfo value is `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`. The `expiry-date` field indicates the expiration time when the Object enters the readable status after the restore is complete.
Owner	container	N/A	The container that stores information about the bucket owner. Child nodes: DisplayName and ID Parent nodes: ListBucketResult.Contents
ID	string	0022012****	The user ID of the bucket owner. Parent nodes: ListBucketResult.Contents.Owner
DisplayName	string	user_example	The name of the object owner. Parent nodes: ListBucketResult.Contents.Owner
CommonPrefixes	container	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

For more information about other common response headers involved in this operation, such as x-oss-request-id and Content-Type, see Common Response Headers.

Examples

Sample request for the simple GetBucket operation

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: 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>100</MaxKeys>
<Delimiter></Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/movie/001.avi</Key>
      <TransitionTime>2024-04-23T07:21:42.000Z</TransitionTime>
      <LastModified>2012-02-24T08:43:07.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/movie/007.avi</Key>
      <LastModified>2012-02-24T08:43:27.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>oss.jpg</Key>
      <LastModified>2012-02-24T06:07:48.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
</ListBucketResult>

Sample request that has the prefix parameter specified

GET /?prefix=fun 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: 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>fun</Prefix>
<Marker></Marker>
<MaxKeys>100</MaxKeys>
<Delimiter></Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/movie/001.avi</Key>
      <LastModified>2012-02-24T08:43:07.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/movie/007.avi</Key>
      <LastModified>2012-02-24T08:43:27.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
</ListBucketResult>

Sample request in which prefix and delimiter parameters are specified

GET /?prefix=fun/&delimiter=/ 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: 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>fun/</Prefix>
<Marker></Marker>
<MaxKeys>100</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<CommonPrefixes>
      <Prefix>fun/movie/</Prefix>
</CommonPrefixes>
</ListBucketResult>

Sample request in which marker parameter is specified

In this example, the max-keys parameter is set to 2, which indicates that the maximum number of objects to return is 2.

GET /?max-keys=2&marker=test1.txt HTTP/1.1
Host: examplebucket.oss-cn-shenzhen.aliyuncs.com
Accept-Encoding: identity
Accept: */*
Connection: keep-alive
User-Agent: aliyun-sdk-python/2.11.0(Darwin/18.2.0/x86_64;3.4.1)
date: Tue, 26 May 2020 08:39:48 GMT
authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

The NextMarker parameter in the response indicates the marker for the next list operation.

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 26 May 2020 08:39:48 GMT
Content-Type: application/xml
Content-Length: 1032
Connection: keep-alive
x-oss-request-id: 5ECCD5D4881816373582xxx
x-oss-server-time: 3

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>examplebucket</Name>
  <Prefix></Prefix>
  <Marker>test1.txt</Marker>
  <MaxKeys>2</MaxKeys>
  <Delimiter></Delimiter>
  <EncodingType>url</EncodingType>
  <IsTruncated>true</IsTruncated>
  <NextMarker>test100.txt</NextMarker>
  <Contents>
    <Key>test10.txt</Key>
    <LastModified>2020-05-26T07:50:18.000Z</LastModified>
    <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
    <Type>Normal</Type>
    <Size>1</Size>
    <StorageClass>Standard</StorageClass>
    <Owner>
      <ID>1305433xxx</ID>
      <DisplayName>1305433xxx</DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>test100.txt</Key>
    <LastModified>2020-05-26T07:50:20.000Z</LastModified>
    <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
    <Type>Normal</Type>
    <Size>1</Size>
    <StorageClass>Standard</StorageClass>
    <Owner>
      <ID>1305433xxx</ID>
      <DisplayName>1305433xxx</DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

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

Assume that examplebucket contains the following three objects: exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt. The storage class of these objects is Cold Archive. The three objects are in the following different states:

No RestoreObject request is submitted for exampleobject1.txt or the RestoreObject request expires.
A RestoreObject request is submitted for exampleobject2.txt, but the restoration is not complete.
A RestoreObject request is submitted for exampleobject3.txt, and the restoration 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

You can use OSS SDKs for the following programming languages to call the GetBucket (ListObjects) operation:

Command-line tool ossutil

For more information about the ossutil command that corresponds to the GetBucket operation, see list-objects (get-bucket).

Error codes

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 users who are granted the `oss:ListObjects` permission can access the bucket.
InvalidArgument	400	The error message returned because the value of max-keys is less than 0 or greater than 1,000. The error message returned because the length of the value of prefix, marker, or delimiter is invalid.