ListBuckets (GetService) - List all buckets | OSS API - Object Storage Service

Usage notes

To list Object Storage Service (OSS) buckets, you must have the oss:ListBuckets permission.

For more information, see Grant a custom policy.

Request syntax

GET / HTTP/1.1
Host: oss.example.com
Date: GMT Date
Authorization: SignatureValue

Request headers

Header

Type

Required

Example

Description

x-oss-resource-group-id

String

No

rg-aek27tc********

The ID of the resource group.

If set to a resource group ID, returns buckets in that resource group.

If set to rg-default-id, returns buckets in the default resource group.
If included without a value, returns buckets in the default resource group.
If omitted, returns all buckets in your Alibaba Cloud account.

Obtain the resource group ID from the Resource Management console or by calling ListResourceGroups. For more information, see View a resource group and ListResourceGroups.

For more information about other common request headers included in a ListBuckets (GetService) request, such as Host and Date, see Common request headers.

Request parameters

Header	Type	Required	Example	Description
prefix	String	No	my	The prefix that returned bucket names must contain. If this parameter is not specified, prefixes are not used to filter returned buckets. Default: empty.
marker	String	No	mybucket10	The bucket name from which listing begins. Buckets alphabetically after this value are returned. If this parameter is not specified, all buckets are returned. Default: empty.
max-keys	Integer	No	10	The maximum number of buckets to return. Valid values: 1 to 1000. Default value: 100.

Response headers

All headers in the response to a ListBuckets (GetService) request are common response headers. For more information, see Common response headers.

Response elements

Note

The ListBuckets (GetService) response XML omits Prefix, Marker, MaxKeys, IsTruncated, and NextMarker when all buckets are returned.

Header	Type	Example	Description
ListAllMyBucketsResult	Container	N/A	The root container for ListBuckets (GetService) results. Child nodes: Owner and Buckets Parent nodes: none
Prefix	String	my	The prefix used to filter returned buckets. Parent nodes: ListAllMyBucketsResult
Marker	String	mybucket	The bucket name from which the ListBuckets (GetService) listing starts. Parent nodes: ListAllMyBucketsResult
MaxKeys	String	10	The maximum number of buckets returned. Parent nodes: ListAllMyBucketsResult
IsTruncated	Enumerated string	true	Whether all results are returned. Valid values: true: Not all results are returned. false: All results are returned. Parent nodes: ListAllMyBucketsResult
NextMarker	String	mybucket10	The pagination marker for retrieving remaining results. Parent nodes: ListAllMyBucketsResult
Owner	Container	N/A	The container for bucket owner details. Parent nodes: ListAllMyBucketsResult
ID	String	ut_test_put_bucket	The user ID of the bucket owner. Parent nodes: ListAllMyBucketsResult.Owner
DisplayName	String	ut_test_put_bucket	The bucket owner display name, which equals the user ID. Parent nodes: ListAllMyBucketsResult.Owner
Buckets	Container	N/A	The container for multiple bucket entries. Child nodes: Bucket Parent nodes: ListAllMyBucketsResult
Bucket	Container	N/A	The container for individual bucket details. Child nodes: Name, CreationDate, and Location Parent nodes: ListAllMyBucketsResult.Buckets
Name	String	mybucket01	The name of the bucket. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket
CreationDate	Time	2014-05-15T11:18:32.000Z	The bucket creation time. Format: `yyyy-mm-ddThh:mm:ss.timezone`. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket
Location	String	oss-cn-hangzhou	The OSS region ID. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket
ExtranetEndpoint	String	oss-cn-hangzhou.aliyuncs.com	The public endpoint of the bucket. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket
IntranetEndpoint	String	oss-cn-hangzhou-internal.aliyuncs.com	The internal endpoint of the bucket. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket
Region	String	cn-hangzhou	The Alibaba Cloud region ID. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket
StorageClass	String	Standard	The storage class of the bucket. Valid values: Standard, IA, Archive, ColdArchive, and DeepColdArchive. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket
ResourceGroupId	String	rg-aek27tc********	The resource group ID of the bucket. Buckets in the default resource group return rg-default-id. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket

Examples

List all buckets in your account

Sample requests

GET / HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample success responses

HTTP/1.1 200 OK
Date: Thu, 15 May 2014 11:18:32 GMT
Content-Type: application/xml
Content-Length: 556
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5374A2880232A65C2300****
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>512**</ID>
    <DisplayName>51264</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <CreationDate>2014-02-17T18:12:43.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-shanghai</Location>
      <Name>app-base-oss</Name>
      <Region>cn-shanghai</Region>
      <StorageClass>Standard</StorageClass>
    </Bucket>
    <Bucket>
      <CreationDate>2014-02-25T11:21:04.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-hangzhou</Location>
      <Name>mybucket</Name>
      <Region>cn-hangzhou</Region>
      <StorageClass>IA</StorageClass>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

List buckets by prefix and max-keys

Sample requests

GET /?prefix=my&max-keys=10 HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample success responses

HTTP/1.1 200 OK
Date: Thu, 15 May 2014 11:18:32 GMT
Content-Type: application/xml
Content-Length: 545
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5374A2880232A65C2300****
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Prefix>my</Prefix>
  <Marker>mybucket</Marker>
  <MaxKeys>10</MaxKeys>
  <IsTruncated>true</IsTruncated>
  <NextMarker>mybucket10</NextMarker>
  <Owner>
    <ID>ut_test_put_bucket</ID>
    <DisplayName>ut_test_put_bucket</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <CreationDate>2014-05-14T11:18:32.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-hangzhou</Location>
      <Name>mybucket01</Name>
      <Region>cn-hangzhou</Region>
      <StorageClass>Standard</StorageClass>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

List buckets in a specific resource group

Sample requests

GET / HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-resource-group-id: rg-aek27tc********

Sample success responses

HTTP/1.1 200 OK
Date: Thu, 15 May 2014 11:18:32 GMT
Content-Type: application/xml
Content-Length: 556
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5374A2880232A65C2300****
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>512**</ID>
    <DisplayName>51264</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <CreationDate>2014-02-07T18:12:43.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-shanghai</Location>
      <Name>test-bucket-1</Name>
      <Region>cn-shanghai</Region>
      <StorageClass>Standard</StorageClass>
      <ResourceGroupId>rg-aek27tc********</ResourceGroupId>
    </Bucket>
    <Bucket>
      <CreationDate>2014-02-05T11:21:04.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-hangzhou</Location>
      <Name>test-bucket-2</Name>
      <Region>cn-hangzhou</Region>
      <StorageClass>IA</StorageClass>
      <ResourceGroupId>rg-aek27tc********</ResourceGroupId>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

List buckets in the default resource group

Sample requests

GET / HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-resource-group-id: rg-default-id

Sample success responses

HTTP/1.1 200 OK
Date: Thu, 15 May 2014 11:18:32 GMT
Content-Type: application/xml
Content-Length: 556
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5374A2880232A65C2300****
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>512**</ID>
    <DisplayName>51264</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <CreationDate>2014-02-07T18:12:43.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-shanghai</Location>
      <Name>test-bucket-3</Name>
      <Region>cn-shanghai</Region>
      <StorageClass>Standard</StorageClass>
      <ResourceGroupId>rg-default-id</ResourceGroupId>
    </Bucket>
    <Bucket>
      <CreationDate>2014-02-05T11:21:04.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-hangzhou</Location>
      <Name>test-bucket-4</Name>
      <Region>cn-hangzhou</Region>
      <StorageClass>IA</StorageClass>
      <ResourceGroupId>rg-default-id</ResourceGroupId>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

SDK

You can use OSS SDKs for the following programming languages to call ListBuckets (GetService):

ossutil

For information about the ossutil command that corresponds to the ListBuckets operation, see list-buckets (get-service).

Error codes

Error code	HTTP status code	Description
AccessDenied	403	The request is from an anonymous user and does not include user authentication information.