Cloud Object Storage GET Service（List Buckets）-API Documentation-Help & Documentation-Tencent Cloud

Feature Overview
This API is used to query the list of all buckets under a requester's account or in a specific region.
Note:
If you create a bucket and immediately call the GET Service API, the response may not include the newly created bucket due to the eventual consistency characteristics of this API.
﻿
Requests
Sample Request
Sample 1
GET / HTTP/1.1
Host: service.cos.myqcloud.com
Date: GMT Date
Authorization: Auth String
Sample 2
GET / HTTP/1.1
Host: cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Note:
Authorization: Auth String (For more information, see Request Signature.)
Host: To query the complete bucket list, specify service.cos.myqcloud.com. To query the bucket list in a specific region, specify cos.<Region>.myqcloud.com, where <Region> is the available region for COS. Refer to the Regions and Access Domain Names documentation for more information.
Request Parameters
GetService supports filtering buckets by bucket tag, region, and creation time through request parameters. To filter buckets by tag, only one tag can be passed in. If a bucket has multiple tags, as long as any of them is hit, the bucket will be returned.
Name
Description
Local Disk Types
Required
tagkey
Filters buckets by bucket tag. Only one tag can be passed in. tagkey is used to pass in the tag key.
string
Not required
tagvalue
Filters buckets by bucket tag. Only one tag can be passed in. tagvalue is used to pass in the tag value.
string
Not required
region
Region based on which buckets are to be filtered, for example, region=ap-beijing. For more information on regions supported by COS, see Regions and Access Endpoints.
string
Not required
create-time
GMT timestamp, used in conjunction with the range parameter, filters buckets based on creation time, for example, create-time=1642662645.
Timestamp
Not required
range
Filters buckets by creation time together with the create-time parameter. Enumerated values: lt (creation time before create-time), gt (creation time after create-time), lte (creation time before or at create-time), gte (creation time after or at create-time).
string
Not required
marker
Starting marker, returns bucket entries in UTF-8 lexicographical order after (excluding) this marker.
string
Not required
max-keys
The maximum number of entries returned in a single response, with a default and maximum value of 2000. If not all buckets are listed in a single response, COS will return a NextMarker node, which can be used as the marker parameter for the next GetService request.
integer
Not required
When the bucket tag authorization differs from the GetService authorization, the authentication and response of the GetService request are as follows. For information on tag authentication authorization methods, see Authorize Sub-account to Retrieve Bucket List by Bucket Tags.
Bucket tag Authorization Status
GetService Authorization Status
GetService Request
Response
The root account passes the bucket tag authorization and grants the sub-account the resource operation permission of the bucket tag tagA.
GetService permission not granted.
With bucket tag parameter tagA
List of buckets containing bucket tag tagA
﻿
﻿
Without bucket tag parameter
Access Denied
﻿
GetService permission granted
With bucket tag parameter tagA
List of buckets containing bucket tag tagA
﻿
﻿
Without bucket tag parameter
List of all buckets
The root account doesn't pass the bucket tag authorization or grant the sub-account the resource operation permission of the bucket tag tagA.
GetService permission not granted.
With bucket tag parameter tagA
Access Denied
﻿
﻿
Without bucket tag parameter
Access Denied
﻿
GetService permission granted
With bucket tag parameter tagA
List of buckets containing bucket tag tagA
﻿
﻿
Without bucket tag parameter
List of all buckets
Request Header
This API only uses Common Request Headers.
Request Body
This API does not have a request body.
Response
Response Header
This API only returns Common Response Headers.
Response Body
A successful query returns application/xml data that includes the list of all buckets or the list of buckets in a specific region.
<ListAllMyBucketsResult>
    <Owner>
        <ID>string</ID>
        <DisplayName>string</DisplayName>
    </Owner>
    <Marker></Marker>
    <NextMarker></NextMarker>
    <IsTruncated></IsTruncated>
    <Buckets>
        <Bucket>
            <Name>string</Name>
            <Location>Enum</Location>
            <CreationDate>date</CreationDate>
        </Bucket>
        <Bucket>
            <Name>string</Name>
            <Location>Enum</Location>
            <CreationDate>date</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>
The nodes are described as follows:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
ListAllMyBucketsResult
-
Stores the result of the GET Service request
Container
Content of ListAllMyBucketsResult:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
Owner
ListAllMyBucketsResult
Bucket owner information
Container
Buckets
ListAllMyBucketsResult
A buckets list
Container
Marker
ListAllMyBucketsResult
Indicates the starting point for this GetService (ListBuckets) operation
string
IsTruncated
ListAllMyBucketsResult
Indicates whether all results have been returned. true: not all results have been returned; false: all results have been returned.
string
NextMarker
ListAllMyBucketsResult
When not all results are returned, use as the marker parameter for the next GetService request.
string
Content of Owner:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
ID
ListAllMyBucketsResult.Owner
Complete ID of the bucket owner, in the format qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
For example, qcs::cam::uin/100000000001:uin/100000000001
string
DisplayName
ListAllMyBucketsResult.Owner
Bucket owner name
string
Content of Buckets:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
Bucket
ListAllMyBucketsResult.Buckets
Bucket information
Container
Content of Buckets.Bucket:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
Name
ListAllMyBucketsResult.Buckets.Bucket
Bucket name, in the format <BucketName-APPID>
For example, examplebucket-1250000000
string
Location
ListAllMyBucketsResult.Buckets.Bucket
Bucket region, for enumeration values, refer to the Regions and Access Domain Names document.
For example, ap-beijing, ap-hongkong, eu-frankfurt, etc.
Enum
CreationDate
ListAllMyBucketsResult.Buckets.Bucket
Bucket creation time in ISO 8601 format. Example: 2019-05-24T10:56:40Z
date
Error Codes
This API returns common error responses and error codes. For more information, see Error Codes.
Examples
Example 1. Querying the list of all buckets
Requests
GET / HTTP/1.1
Host: service.cos.myqcloud.com
Date: Fri, 24 May 2019 11:59:50 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1558699190;1558706390&q-key-time=1558699190;1558706390&q-header-list=date;host&q-url-param-list=&q-signature=89fa1f6a56c34e460f3db4d65f928eaf034a**
Connection: close
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 805
Connection: close
Date: Fri, 24 May 2019 11:59:51 GMT
Server: tencent-cos
x-cos-request-id: NWNlN2RjYjdfOGFiMjM1MGFfNTVjMl8zMmI1****
﻿
<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    </Marker>
    </NextMarker>
    <IsTruncated>false</IsTruncated>
    <Buckets>
        <Bucket>
            <Name>examplebucket1-1250000000 </Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:49:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket2-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:51:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket3-1250000000</Name>
            <Location>eu-frankfurt</Location>
            <CreationDate>2019-05-24T11:53:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket4-1250000000</Name>
            <Location>eu-frankfurt</Location>
            <CreationDate>2019-05-24T11:55:50Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>
Example 2. Querying the list of buckets in a specific region (filtered by domain name)
Requests
GET / HTTP/1.1
Host: cos.ap-beijing.myqcloud.com
Date: Fri, 24 May 2019 11:59:51 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1558699191;1558706391&q-key-time=1558699191;1558706391&q-header-list=date;host&q-url-param-list=&q-signature=c3f55f4ce2800fb343cf85ff536a9185a0c1**
Connection: close
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 495
Connection: close
Date: Fri, 24 May 2019 11:59:51 GMT
Server: tencent-cos
x-cos-request-id: NWNlN2RjYjdfZjhjODBiMDlfOWNlNF9hYzc2****
﻿
<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    </Marker>
    </NextMarker>
    <IsTruncated>false</IsTruncated>
    <Buckets>
        <Bucket>
            <Name>examplebucket1-1250000000 </Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:49:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket2-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:51:50Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>
Example 3. Querying the list of buckets in a specific region (filtered by request parameter)
Requests
GET /?region=ap-beijing HTTP/1.1
Host: service.cos.myqcloud.com
Date: Fri, 24 May 2019 11:59:51 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1558699191;1558706391&q-key-time=1558699191;1558706391&q-header-list=date;host&q-url-param-list=&q-signature=c3f55f4ce2800fb343cf85ff536a9185a0c1**
Connection: close
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 495
Connection: close
Date: Fri, 24 May 2019 11:59:51 GMT
Server: tencent-cos
x-cos-request-id: NWNlN2RjYjdfZjhjODBiMDlfOWNlNF9hYzc2****
﻿
<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    </Marker>
    </NextMarker>
    <IsTruncated>false</IsTruncated>
    <Buckets>
        <Bucket>
            <Name>examplebucket1-</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:49:50Z</CreationDate>
        </Bucket>
        <Bucket>
            <Name>examplebucket2-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2019-05-24T11:51:50Z</CreationDate>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>
Example 4. Filtering buckets by the specified tag
The tag for bucket examplebucket-1250000000 is <key1, value1>, and the tags for bucket examplebucket1-1250000000 are <key1, value1> and <key2, value2>.
Requests
GET /?tagkey=key1&tagvalue=value1 HTTP/1.1
Host: service.cos.myqcloud.com
Date: Fri, 24 May 2019 11:59:51 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1558699191;1558706391&q-key-time=1558699191;1558706391&q-header-list=date;host&q-url-param-list=&q-signature=c3f55f4ce2800fb343cf85ff536a9185a0c1**
Connection: close
Response
HTTP/1.1 200 OK
Content-Length: 378
Content-Type: application/xml
Server: tencent-cos
Connection: keep-alive
Date: Thu, 20 Oct 2022 07:29:40 GMT
x-cos-request-id: NjM1MGY4ZTRfMWViMjM1MGFfYjg3MV8xNjdk****
﻿
<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    </Marker>
    </NextMarker>
    <IsTruncated>false</IsTruncated>
    <Buckets>
        <Bucket>
            <Name>examplebucket-1250000000</Name>
            <Location>ap-guangzhou</Location>
            <CreationDate>2022-04-11T03:01:49Z</CreationDate>
            <BucketType>cos</BucketType>
        </Bucket>
    </Buckets>
    <Buckets>
        <Bucket>
            <Name>examplebucket1-1250000000 </Name>
            <Location>ap-guangzhou</Location>
            <CreationDate>2022-04-12T03:01:49Z</CreationDate>
            <BucketType>cos</BucketType>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>
Example 5. Filtering buckets by creation time
List buckets created before 2022-1-20 15:10:45.
Requests
GET /?range=lt&create-time=1642662645 HTTP/1.1
Host: service.cos.myqcloud.com
User-Agent: curl/7.64.1
Accept: */*
Authorization: q-sign-algorithm=sha1&q-ak=AKIDYv3vWrwkHXVDfqk*&q-sign-time=1667448802;1668448852&q-key-time=1667448802;1668448852&q-url-param-list=create-time;range&q-header-list=host&q-signature=a043c0593c8c4cd1caf570**
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 5566
Connection: keep-alive
Date: Thu, 03 Nov 2022 04:14:23 GMT
Server: tencent-cos
x-cos-request-id: NjM2MzQwMWZfMmJiMjM1MGFfYTc**
﻿
<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    </Marker>
    </NextMarker>
    <IsTruncated>false</IsTruncated>
    <Buckets>
        <Bucket>
            <Name>examplebucket-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2021-11-23T03:02:12Z</CreationDate>
            <BucketType>cos</BucketType>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>
Example 6. Querying the bucket list with pagination
Requests
GET /?max-keys=1 HTTP/1.1
Host: service.cos.myqcloud.com
User-Agent: curl/7.64.1
Accept: */*
Authorization: q-sign-algorithm=sha1&q-ak=AKIDYv3vWrwkHXVDfqk*&q-sign-time=1667448802;1668448852&q-key-time=1667448802;1668448852&q-url-param-list=create-time;range&q-header-list=host&q-signature=a043c0593c8c4cd1caf570**
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 5566
Connection: keep-alive
Date: Thu, 03 Nov 2022 04:14:23 GMT
Server: tencent-cos
x-cos-request-id: NjM2MzQwMWZfMmJiMjM1MGFfYTc**
﻿
<ListAllMyBucketsResult>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>100000000001</DisplayName>
    </Owner>
    </Marker>
    <NexMarker>1</NextMarker>
    <IsTruncated>true</IsTruncated>
    <Buckets>
        <Bucket>
            <Name>examplebucket-1250000000</Name>
            <Location>ap-beijing</Location>
            <CreationDate>2021-11-23T03:02:12Z</CreationDate>
            <BucketType>cos</BucketType>
        </Bucket>
    </Buckets>
</ListAllMyBucketsResult>
﻿

Bucket tag Authorization Status	`GetService` Authorization Status	`GetService` Request	Response
The root account passes the bucket tag authorization and grants the sub-account the resource operation permission of the bucket tag `tagA`.	`GetService` permission not granted.	With bucket tag parameter `tagA`	List of buckets containing bucket tag `tagA`
	`GetService` permission not granted.			Without bucket tag parameter	Access Denied
		`GetService` permission granted	With bucket tag parameter `tagA`	List of buckets containing bucket tag `tagA`
		`GetService` permission granted		Without bucket tag parameter	List of all buckets
The root account doesn't pass the bucket tag authorization or grant the sub-account the resource operation permission of the bucket tag `tagA`.	`GetService` permission not granted.	With bucket tag parameter `tagA`	Access Denied
	`GetService` permission not granted.			Without bucket tag parameter	Access Denied
		`GetService` permission granted	With bucket tag parameter `tagA`	List of buckets containing bucket tag `tagA`
		`GetService` permission granted		Without bucket tag parameter	List of all buckets

Name	Description	Local Disk Types	Required
tagkey	Filters buckets by bucket tag. Only one tag can be passed in. `tagkey` is used to pass in the tag key.	string	Not required
tagvalue	Filters buckets by bucket tag. Only one tag can be passed in. `tagvalue` is used to pass in the tag value.	string	Not required
region	Region based on which buckets are to be filtered, for example, `region=ap-beijing`. For more information on regions supported by COS, see Regions and Access Endpoints.	string	Not required
create-time	GMT timestamp, used in conjunction with the `range` parameter, filters buckets based on creation time, for example, `create-time=1642662645`.	Timestamp	Not required
range	Filters buckets by creation time together with the `create-time` parameter. Enumerated values: lt (creation time before `create-time`), gt (creation time after `create-time`), lte (creation time before or at `create-time`), gte (creation time after or at `create-time`).	string	Not required
marker	Starting marker, returns bucket entries in UTF-8 lexicographical order after (excluding) this marker.	string	Not required
max-keys	The maximum number of entries returned in a single response, with a default and maximum value of 2000. If not all buckets are listed in a single response, COS will return a NextMarker node, which can be used as the `marker` parameter for the next GetService request.	integer	Not required

Node Name (Keyword)	Parent Node	Description	Local Disk Types
ListAllMyBucketsResult	-	Stores the result of the `GET Service` request	Container

GET Service（List Buckets）

On this page:

Feature Overview

Requests

Sample Request

Request Parameters

Request Header

Request Body

Response

Response Header

Response Body

Error Codes

Examples

Example 1. Querying the list of all buckets

Requests

Response

Example 2. Querying the list of buckets in a specific region (filtered by domain name)

Requests

Response

Example 3. Querying the list of buckets in a specific region (filtered by request parameter)

Requests

Response

Example 4. Filtering buckets by the specified tag

Requests

Response

Example 5. Filtering buckets by creation time

Requests

Response

Example 6. Querying the bucket list with pagination

Requests

Response