Unlock the Power of AI

1 million free tokens

88% Price Reduction

Activate Now
Home PageObject Storage ServiceDeveloper ReferenceAPI ReferenceBucket operationsBasic operationsGetBucket(ListObjects)
Search for Help Content

GetBucket(ListObjects)

Updated at: 2025-03-21 08:30
Product
Community

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

Usage notes

  • The GetBucket (ListObjects) operation is updated to GetBucketV2 (ListObjectsV2). When you develop your applications, we recommend that you call the GetBucketV2 (ListObjectsV2) operation. To provide backward compatibility, OSS continues to support the GetBucket (ListObjects) operation. For more information about GetBucketV2 (ListObjectsV2), see ListObjectsV2 (GetBucketV2).

  • The user metadata of objects is not returned for GetBucket (ListObjects) requests.

  • The GetBucket (ListObjects) operation is performed on buckets. You are charged for PUT requests based on the storage class of the bucket. You are charged an API calling fee each time you call the GetBucket (ListObjects) operation. For more information, see API operation calling fees.

Request syntax

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

Request headers

A GetBucket (ListObjects) request contains only common request headers, such as Authorization and Host. For more information, see Common request headers.

Request parameters

Parameter

Type

Required

Example

Description

Parameter

Type

Required

Example

Description

delimiter

String

No

/

The character that you want to use to group objects by name. If you specify the delimiter parameter in the request, the response contains the CommonPrefixes parameter. The 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 parameter is left empty.

marker

String

No

test1.txt

The name of the object after which the ListObjects (GetBucket) operation starts. If this parameter is specified, objects whose names are alphabetically after the marker 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 parameter is left empty.

max-keys

String

No

200

The maximum number of objects that can be returned. If the list operation cannot be complete at a time due to the max-keys parameter settings, the NextMarker parameter 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 in the names of the objects that you want to list.

  • The value of prefix must be smaller than 1,024 bytes in length.

  • If you specify a prefix, the names of the returned objects contain the prefix.

If prefix is set to a directory name in the request, the objects whose names contain this prefix are listed, which includes 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 parameter. However, objects and directories in the subdirectories are not listed.

For example, a bucket contains the following 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 parameter is left empty.

encoding-type

String

No

url

The encoding type of the object names in the response.

By default, this parameter is left empty.

Valid value: url

Important

The values of delimiter, marker, prefix, NextMarker, and Key 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 the encoding-type parameter to encode the value in the response.

Response elements

Element

Type

Example

Description

Element

Type

Example

Description

ListBucketResult

Container

N/A

The container that stores the response to the GetBucket (ListObjects) operation.

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

Parent node: None

Name

String

oss-example

The name of the bucket.

Parent node: ListBucketResult

Prefix

String

fun/

The prefix contained in the names of the returned buckets.

Parent nodes: ListBucketResult or CommonPrefixes

Marker

String

test1.txt

The name of the object after which the list operation starts.

Parent node: ListBucketResult

MaxKeys

String

100

The maximum number of returned objects in the response.

Parent node: ListBucketResult

Delimiter

String

/

The character that is used to group objects by name. The 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 the CommonPrefixes parameter.

Parent node: 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 parameters in the response are encoded: Delimiter, Marker, Prefix, NextMarker, and Key.

Parent node: ListBucketResult

IsTruncated

Enumerated string

false

Indicates whether the returned results are 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 node: ListBucketResult

NextMarker

String

test100.txt

The position from which the next list operation starts.

Parent node: ListBucketResult

Contents

Container

N/A

The container that stores 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 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 node: ListBucketResult.Contents

LastModified

Time

2012-02-24T08:42:32.000Z

The last modified time of the object.

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 node: 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 that is calculated based on a specific rule.

  • The ETag value of an object can be used to check whether the object content is modified. We recommend that you use the MD5 hash of an object rather than the ETag value of the object to verify data integrity.

Parent node: ListBucketResult.Contents

Type

String

Normal

The type of the object. Valid values:

  • 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 is created by calling the PutSymlink operation.

Size

String

344606

The size of the returned object. Unit: bytes.

Parent node: ListBucketResult.Contents

StorageClass

String

Standard

The storage class of the object.

Parent node: ListBucketResult.Contents

RestoreInfo

String

ongoing-request="true"

The restoration status 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.

Owner

Container

N/A

The container that stores information about the bucket owner.

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

If Delimiter is specified in the request, the response contains the CommonPrefixes parameter. The 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 the CommonPrefixes parameter.

Parent node: ListBucketResult

For more information about common response headers, such as x-oss-request-id and Content-Type, see Common response headers.

Examples

  • Sample request for a simple ListObjectsV2 (GetBucketV2) operation 

    GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

    Sample success 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>
<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 in which the prefix parameter is specified 

    GET /?prefix=fun HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6q**************:77Dv****************

    Sample success 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>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: OSS qn6q**************:77Dv****************

    Sample success 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>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: OSS qn6q**************:77Dv****************

    Sample success responses

    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 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: OSS qn6q**************:77Dv****************

    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>

OSS SDKs

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

ossutil

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

Error codes

Error code

HTTP status code

Description

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.

Previous: DeleteBucketNext: ListObjectsV2 (GetBucketV2)
  • On this page （1）
  • Usage notes
  • Request syntax
  • Request headers
  • Request parameters
  • Response elements
  • Examples
  • OSS SDKs
  • ossutil
  • Error codes
Feedback
phone Contact Us

Chat now with Alibaba Cloud Customer Service to assist you in finding the right products and services to meet your needs.

alicare alicarealicarealicare