ListCname

ListCname queries all custom domain names (CNAMEs) that are mapped to a bucket. For an Agentic Bucket, the response may contain both exact CNAME and wildcard CNAME entries, and the IsWildCard element identifies the wildcard CNAME entries.

Usage notes

In the response, an exact CNAME entry does not include the IsWildCard element, which keeps the response compatible with earlier versions of OSS SDKs. A wildcard CNAME entry includes the IsWildCard element set to true, and its Domain value is the base domain name without the *. prefix.
The response for an Agentic Bucket may contain both exact CNAME and wildcard CNAME entries. The response format for a standard bucket remains unchanged.

Request syntax

GET /?cname HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Request headers

This operation uses only common request headers. For more information, see Common HTTP headers.

Response headers

This operation returns only common response headers. For more information, see Common HTTP headers.

Response elements

Element	Type	Example	Description
ListCnameResult	Container	N/A	The container that stores the queried CNAME information. Parent nodes: none Child nodes: Bucket, Owner, and Cname
Bucket	String	examplebucket	The name of the bucket whose CNAMEs are queried. Parent nodes: ListCnameResult Child nodes: none
Owner	String	testowner	The name of the bucket owner. Parent nodes: ListCnameResult Child nodes: none
Cname	Container	N/A	The container that stores the CNAME information. Parent nodes: ListCnameResult Child nodes: Domain, LastModified, Status, IsWildCard, and Certificate
Domain	String	example.com	The custom domain name. For a wildcard CNAME entry, this value is the base domain name without the `*.` prefix, such as example.com. Parent nodes: Cname Child nodes: none
LastModified	String	2021-09-15T02:35:07.000Z	The time when the custom domain name was mapped. Parent nodes: Cname Child nodes: none
Status	String	Enabled	The state of the domain name. Valid values: Enabled: The domain name is enabled. Disabled: The domain name is disabled. Parent nodes: Cname Child nodes: none
IsWildCard	Boolean	true	Indicates whether the entry is a wildcard CNAME. Only a wildcard CNAME entry includes this element, and its value is true. An exact CNAME entry does not include this element, which keeps the response compatible with earlier versions of OSS SDKs. Parent nodes: Cname Child nodes: none
Certificate	Container	N/A	The container that stores the certificate information. Parent nodes: Cname Child nodes: Type, CertId, Status, CreationDate, Fingerprint, ValidStartDate, and ValidEndDate
Type	String	CAS	The source of the certificate. Valid values: CAS: The certificate is obtained from Certificate Management Service. Upload: The certificate was uploaded by the user to an earlier version of the certificate hosting service. Parent nodes: Certificate Child nodes: none
CertId	String	493****-cn-hangzhou	The ID of the certificate. Parent nodes: Certificate Child nodes: none
Status	String	Enabled	The state of the certificate. Valid values: Enabled: The certificate is in use. Disabled: The certificate is not in use. Parent nodes: Certificate Child nodes: none
CreationDate	String	Wed, 15 Sep 2021 02:35:06 GMT	The time when the certificate was bound. Parent nodes: Certificate Child nodes: none
Fingerprint	String	DE:01:CF:EC:7C:A7:98:CB:D8:6E:FB:1D:97:EB:A9:64:1D:4E::	The fingerprint of the certificate. Parent nodes: Certificate Child nodes: none
ValidStartDate	String	Wed, 12 Apr 2023 10:14:51 GMT	The time when the certificate takes effect. Parent nodes: Certificate Child nodes: none
ValidEndDate	String	Mon, 4 May 2048 10:14:51 GMT	The time when the certificate expires. Parent nodes: Certificate Child nodes: none

Examples

Sample request

GET /?cname HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Tues, 11 May 2022 11:39:12 GMT
Authorization: OSS qn6q**************:77Dv****************

Sample responses

Sample response for a standard bucket

content-length: 1855
x-oss-console-auth: success
server: AliyunOSS
x-oss-server-time: 7
connection: keep-alive
x-oss-request-id: 614169F1AE63BD37355CA12B
date: Tues, 11 May 2022 11:39:12 GMT
content-type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ListCnameResult>
  <Bucket>targetbucket</Bucket>
  <Owner>testowner</Owner>
  <Cname>
    <Domain>example.com</Domain>
    <LastModified>2021-09-15T02:35:07.000Z</LastModified>
    <Status>Enabled</Status>
    <Certificate>
      <Type>CAS</Type>
      <CertId>493****-cn-hangzhou</CertId>
      <Status>Enabled</Status>
      <CreationDate>Wed, 15 Sep 2021 02:35:06 GMT</CreationDate>
      <Fingerprint>DE:01:CF:EC:7C:A7:98:CB:D8:6E:FB:1D:97:EB:A9:64:1D:4E:**:**</Fingerprint>
      <ValidStartDate>Wed, 12 Apr 2023 10:14:51 GMT</ValidStartDate>
      <ValidEndDate>Mon, 4 May 2048 10:14:51 GMT</ValidEndDate>
    </Certificate>
  </Cname>
  <Cname>
    <Domain>example.org</Domain>
    <LastModified>2021-09-15T02:34:58.000Z</LastModified>
    <Status>Enabled</Status>
  </Cname>
</ListCnameResult>

Sample response for an Agentic Bucket, which may contain both exact CNAME and wildcard CNAME entries

content-length: 1024
x-oss-console-auth: success
server: AliyunOSS
x-oss-server-time: 7
connection: keep-alive
x-oss-request-id: 614169F1AE63BD37355CA12C
date: Tues, 11 May 2022 11:39:12 GMT
content-type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ListCnameResult>
  <Bucket>myab-$uid-$region-ab-apsr</Bucket>
  <Owner>1234567890123456</Owner>
  <Cname>
    <Domain>console.example.com</Domain>
    <LastModified>2025-04-17T02:35:07.000Z</LastModified>
    <Status>Enabled</Status>
  </Cname>
  <Cname>
    <Domain>example.com</Domain>
    <LastModified>2025-04-17T02:50:34.000Z</LastModified>
    <Status>Enabled</Status>
    <IsWildCard>true</IsWildCard>
  </Cname>
</ListCnameResult>

OSS SDKs

The following OSS SDKs support the ListCname operation:

ossutil

For information about the ossutil command that corresponds to the ListCname operation, see list-cname.

Error codes

Error code	HTTP status code	Description
AccessDenied	403	You do not have the permissions to call the ListCname operation. Only the bucket owner and users who are granted the `oss:ListCname` permission can query all CNAMEs that are mapped to the current bucket.
NoSuchCname	404	No CNAME is mapped to the bucket.
MethodNotAllowed	405	The CNAME feature is not enabled for the target bucket type.