ListCustomHostnames - Edge Security Acceleration - Alibaba Cloud Documentation Center

Queries the Software as a Service (SaaS) domain names for a site. This operation returns the ID, status, and domain validation information for each SaaS domain name. You can filter the results by the SaaS domain name, site ID, or the ID of the attached record.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request parameters

Parameter	Type	Required	Description	Example
SiteId	integer	Yes	The site ID. Obtain this ID by calling the ListSites operation.	744571165985008
RecordId	integer	No	The ID of the attached record. Obtain this ID by calling the ListRecords operation.	1234567890123
Hostname	string	No	The SaaS domain name.	custom.site.com
NameMatchType	string	No	The match pattern for searching SaaS domain names. The default value is `exact`. prefix: Prefix match. suffix: Suffix match. exact: Exact match. fuzzy: Fuzzy match.	exact
Status	string	No	The status of the SaaS domain name. pending: Pending validation. active: Active. conflicted: Conflicted. offline: Offline.	active
PageNumber	integer	No	The page number. Pages start from 1. The default value is 1.	1
PageSize	integer	No	The number of entries per page. The default value is 100. The maximum value is 500.	100

Response elements

Element	Type	Description	Example
	object
RequestId	string	The unique ID of the request.	04F0F334-1335-436C-A1D7-6C044FE73368
PageNumber	integer	The page number.	1
PageSize	integer	The number of entries per page.	100
TotalCount	integer	The total number of SaaS domain names.	10
Hostnames	array<object>	The list of SaaS domain names.
	object	The information about a single SaaS domain name.
HostnameId	integer	The ID of the SaaS domain name.	1234567890123
Hostname	string	The SaaS domain name.	custom.site.com
SiteId	integer	The site ID.	890601022130656
SiteName	string	The site name.	example.com
RecordId	integer	The record ID.	3386032455886912
RecordName	string	The record name.	origin.example.com
Status	string	The status of the SaaS domain name. pending: Pending validation. active: Active. conflicted: Conflicted. offline: Offline.	active
SslFlag	string	The SSL switch. on: SSL is enabled. off: SSL is disabled.	on
CertType	string	The certificate type. free: Free certificate. upload: Uploaded certificate. cas: Alibaba Cloud Security certificate.	free
CertHttpKey	string	The HTTP URL for certificate validation.	http://custom.site.com/.well-known/acme-challenge/jLmMHlEaZ3jb352Qo3ciaSoAC8KZ5Hk0F-4_1xLQtgc
CertHttpValue	string	The HTTP content for certificate validation.	jLmMHlEaZ3jb352Qo3ciaSoAC8KZ5Hk0F-4_1xLQtgc.GridYdfJJB5PgFEL-t89XfaFvMPB4f2-I9fwLpKl6e0
CertTxtKey	string	The TXT name for certificate validation.	_acme-challenge.custom.site.com
CertTxtValue	string	The TXT content for certificate validation.	lcKYad3UQXgrZLvMm_6TBUYKK4xTkGmninV0Mzx4gjM
VerifyHost	string	The TXT name for domain validation.	_esa_custom_hostname.custom.site.com
VerifyCode	string	The TXT content for domain validation.	verify_16ab7f4d389d4dff6655f995c6a997bd
CertStatus	string	The certificate status. OK: Normal. Applying: Applying. ApplyFailed: Application failed. Expiring: Expiring soon. Expired: Expired.	OK
CertNotAfter	string	The expiration time of the certificate. The date is in the ISO 8601 format and uses UTC. The format is `yyyy-MM-ddTHH:mm:ssZ`.	2026-04-19T11:15:20Z
CertApplyMessage	string	The error description for the free certificate application.	canceled
CertApplyCode	integer	The error code for the free certificate application.	2
OfflineReason	string	The reason why the SaaS domain name was taken offline. expiration_arrears: The subscription plan expired or the account has an overdue payment. internally_disabled: Disabled by the system. missing_icp: The domain name lacks an ICP filing. content_violation: Content violation. proactively_disabled: Disabled by you or because the usage cap was reached.	missing_icp
ConflictWith	string	The reason why the SaaS domain name is conflicted. existing_custom_hostname: Conflicts with an existing SaaS domain name. existing_record: Conflicts with an existing site record. existing_load_balancer: Conflicts with an existing load balancer. existing_origin_pool: Conflicts with an existing origin pool.	existing_custom_hostname
CreateTime	string	The creation time of the SaaS domain name. The date is in the ISO 8601 format and uses UTC. The format is `yyyy-MM-ddTHH:mm:ssZ`.	2026-04-19T11:15:20Z
UpdateTime	string	The update time of the SaaS domain name. The date is in the ISO 8601 format and uses UTC. The format is `yyyy-MM-ddTHH:mm:ssZ`.	2026-04-19T11:15:20Z

Examples

Success response

JSON format

{
  "RequestId": "04F0F334-1335-436C-A1D7-6C044FE73368",
  "PageNumber": 1,
  "PageSize": 100,
  "TotalCount": 10,
  "Hostnames": [
    {
      "HostnameId": 1234567890123,
      "Hostname": "custom.site.com",
      "SiteId": 890601022130656,
      "SiteName": "example.com",
      "RecordId": 3386032455886912,
      "RecordName": "origin.example.com",
      "Status": "active",
      "SslFlag": "on",
      "CertType": "free",
      "CertHttpKey": "http://custom.site.com/.well-known/acme-challenge/jLmMHlEaZ3jb352Qo3ciaSoAC8KZ5Hk0F-4_1xLQtgc",
      "CertHttpValue": "jLmMHlEaZ3jb352Qo3ciaSoAC8KZ5Hk0F-4_1xLQtgc.GridYdfJJB5PgFEL-t89XfaFvMPB4f2-I9fwLpKl6e0",
      "CertTxtKey": "\t\n_acme-challenge.custom.site.com\n",
      "CertTxtValue": "\t\nlcKYad3UQXgrZLvMm_6TBUYKK4xTkGmninV0Mzx4gjM\n",
      "VerifyHost": "_esa_custom_hostname.custom.site.com\n",
      "VerifyCode": "verify_16ab7f4d389d4dff6655f995c6a997bd\n",
      "CertStatus": "OK",
      "CertNotAfter": "2026-04-19T11:15:20Z\n",
      "CertApplyMessage": "canceled",
      "CertApplyCode": 2,
      "OfflineReason": "missing_icp",
      "ConflictWith": "existing_custom_hostname",
      "CreateTime": "2026-04-19T11:15:20Z",
      "UpdateTime": "2026-04-19T11:15:20Z"
    }
  ]
}

Error codes

HTTP status code	Error code	Error message	Description
400	InternalException	Failed to call the service. Try again later or contact technical support.	Failed to call the service. Try again later or contact technical support.
400	InvalidParameter	The specified parameter is invalid.	The specified parameter is invalid.
404	CustomHostname.NotFound	The custom hostname does not exist. Modify it and try again.	The custom hostname does not exist. Modify it and try again.
404	CustomHostname.ApplyCertFailed	Fail to apply a free cert for custom hostname. Please try again later.
404	CustomHostname.SetCertFailed	Fail to deploy a cert for custom hostname. Please try again later.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.