All Products
Search

This Product

    Object Storage Service:GetBucket (ListObjects)

    Document Center

    Object Storage Service:GetBucket (ListObjects)

    Last Updated:Jun 02, 2026

    Lists information about all objects in a bucket, including the object name, size, and last modified time.

    Usage notes

    • The GetBucket (ListObjects) operation is superseded by GetBucketV2 (ListObjectsV2). Use GetBucketV2 (ListObjectsV2) for new applications. OSS still supports GetBucket (ListObjects). GetBucketV2 (ListObjectsV2) is documented in ListObjectsV2 (GetBucketV2).

    • Custom object metadata is not returned in the response to a GetBucket (ListObjects) request.

    • GetBucket (ListObjects) is a bucket-level operation. Each call is billed as one PUT request based on the bucket storage class (PUT API requests).

    • If versioning is enabled, overwriting or deleting objects creates delete markers and previous versions. To avoid performance degradation when listing objects, configure lifecycle rules to periodically remove unneeded delete markers and previous versions.

    Request syntax

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

    Request headers

    This operation uses only common request headers such as Authorization and Host. Common request headers.

    Request parameters

    Name

    Type

    Required

    Example

    Description

    delimiter

    String

    No

    /

    Groups object names. Objects with the same string from the prefix to the first delimiter occurrence are grouped into a CommonPrefixes element.

    Default value: none.

    marker

    String

    No

    test1.txt

    The object from which the listing operation begins. Objects are returned in alphabetical order after the specified marker.

    Used for pagination. Must be less than 1,024 bytes.

    Even if the marker does not exist, listing starts from the next object in alphabetical order.

    Default value: none.

    max-keys

    String

    No

    200

    Maximum number of objects to return. If results are truncated, the response includes a NextMarker value for pagination.

    Valid values: 1 to 1000.

    Default value: 100.

    prefix

    String

    No

    fun

    Lists only objects whose names contain this prefix.

    • Must be less than 1,024 bytes.

    • Returned keys include the prefix.

    Setting prefix to a directory name lists all objects and subdirectories recursively.

    If you also set delimiter to a forward slash (/), only objects in the directory are listed. Subdirectory names are returned in CommonPrefixes, and their contents 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/, the three objects are returned. If you set prefix to fun/ and delimiter to a forward slash (/), fun/test.jpg and fun/movie/ are returned.

    Default value: none.

    encoding-type

    String

    No

    url

    The encoding type of the content in the response.

    Default value: none.

    Valid value: url

    Important

    Values of delimiter, marker, prefix, NextMarker, and Key are UTF-8 encoded. Specify encoding-type to encode values containing control characters unsupported by XML 1.0.

    Response elements

    Name

    Type

    Example

    Description

    ListBucketResult

    Container

    N/A

    The container for the results of a GetBucket request.

    Child nodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, and Contents

    Parent node: None

    Name

    String

    oss-example

    The bucket name.

    Parent node: ListBucketResult

    Prefix

    String

    fun/

    The prefix of the query results.

    Parent nodes: ListBucketResult or CommonPrefixes

    Marker

    String

    test1.txt

    The start position of this GetBucket (ListObjects) operation.

    Parent node: ListBucketResult

    MaxKeys

    String

    100

    The maximum number of results returned in the response.

    Parent node: ListBucketResult

    Delimiter

    String

    /

    The character used to group object names. Objects with the same string from the prefix to the first Delimiter occurrence are grouped into a CommonPrefixes element.

    Parent node: ListBucketResult

    EncodingType

    String

    url

    The encoding type used for the returned results. If you specify the encoding-type parameter in the request, the Delimiter, Marker, Prefix, NextMarker, and Key elements in the response are encoded.

    Parent node: ListBucketResult

    IsTruncated

    Enumerated string

    false

    Whether the returned results are truncated.

    Valid values: true and false

    • true: Not all results are returned.

    • false: All results are returned.

    Parent node: ListBucketResult

    NextMarker

    String

    test100.txt

    The start position of the next listing.

    Parent node: ListBucketResult

    Contents

    Container

    N/A

    The container for the metadata of each returned object.

    Parent node: ListBucketResult

    Key

    String

    fun/test.jpg

    The key of the object.

    Parent node: ListBucketResult.Contents

    TransitionTime

    Time

    2024-04-23T07:21:42.000Z

    The time when the object was transitioned to the Cold Archive or Deep Cold Archive storage class based on a lifecycle rule.

    Note

    • If you delete a Cold Archive or Deep Cold Archive object more than 180 days after it is converted, no early deletion fee is charged. If you delete the object within 180 days after it is converted, an early deletion fee is charged.

    • This field cannot be used to determine the time when an object is converted to the IA or Archive storage class by a lifecycle rule. Whether an IA or Archive object meets the minimum storage duration requirement depends on the Last-Modified time.

    Parent node: ListBucketResult.Contents

    SealedTime

    Time

    2020-05-21T12:07:15.000Z

    The time when the seal operation was performed on the object.

    Note

    This field is returned only for appendable objects created by AppendObject that have been sealed.

    Parent node: ListBucketResult.Contents

    LastModified

    Time

    2012-02-24T08:42:32.000Z

    The time when the object was last modified.

    Note

    • The minimum storage duration for objects in the Infrequent Access storage class is 30 days. The duration is calculated from the Last-Modified time of the object. If you delete an object more than 30 days after its Last-Modified time, no early deletion fee is charged.

    • The minimum storage duration for objects in the Archive Storage class is 60 days. The duration is calculated from the Last-Modified time of the object. If you delete an object more than 60 days after its Last-Modified time, no early deletion fee is charged.

    Parent node: ListBucketResult.Contents

    ETag

    String

    5B3C1A2E053D763E1B002CC607C5A0FE1****

    The entity tag (ETag), generated at object creation to identify object content.

    • For an object created by a PutObject request, the ETag value is the MD5 hash of the object content.

    • For an object created by other methods, the ETag is a unique value calculated by a specific rule, not the MD5 hash of the object content.

    • Use ETags to detect content changes, not to verify data integrity.

    Parent node: ListBucketResult.Contents

    Type

    String

    Normal

    The object type. Valid values:

    • Normal: The object is created by a simple upload.

    • Multipart: The object is created by a multipart upload.

    • Appendable: The object is created by an append upload.

    • Symlink: The symbolic link is created by the PutSymlink operation.

    Size

    String

    344606

    The size of the returned object in bytes.

    Parent node: ListBucketResult.Contents

    StorageClass

    String

    Standard

    The storage class of the object.

    Parent node: ListBucketResult.Contents

    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.

    Owner

    Container

    N/A

    Container for the bucket owner information.

    Child nodes: DisplayName and ID

    Parent node: ListBucketResult.Contents

    ID

    String

    0022012****

    The user ID of the bucket owner.

    Parent node: ListBucketResult.Contents.Owner

    DisplayName

    String

    user_example

    The name of the object owner.

    Parent node: ListBucketResult.Contents.Owner

    CommonPrefixes

    Container

    N/A

    Returned when Delimiter is specified. Contains a set of object name prefixes that share a common prefix and end with the delimiter.

    Parent node: ListBucketResult

    Other common response headers such as x-oss-request-id and Content-Type are described in Common response headers.

    Examples

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

    • Request with the prefix parameter

      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>

    • Request with the prefix and delimiter parameters

      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>

    • Paginated request that specifies the marker parameter

      In this example, max-keys is set to 2 to return a maximum of two objects.

      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

      Use the NextMarker value from the response as the marker for the next request.

      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>

    • 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 calling this operation:

    ossutil command-line tool

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

    Error codes

    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.