GetCustomHostname - Edge Security Acceleration - Alibaba Cloud Documentation Center

Retrieves the detailed configuration of a specific Software as a Service (SaaS) domain name. The configuration includes the TXT record name and value for domain name validation, and the certificate expiration time when SSL is enabled.

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
HostnameId	integer	Yes	The ID of the SaaS domain name. You can obtain this ID by calling the ListCustomHostnames operation.	1234567890123

Response elements

Element	Type	Description	Example
	object
RequestId	string	The unique ID generated by Alibaba Cloud for the request.	7C414690-9D7B-5D66-9CD9-AD0B3F25ED49
CustomHostnameModel	object	The information about the 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.	4042843419650112
RecordName	string	The record name.	origin.example.com
Status	string	The status of the SaaS domain name. pending: Pending validation. active: Active. conflicted: In use. offline: Offline.	active
VerifyHost	string	The TXT record name for domain validation.	_esa_custom_hostname.custom.site.com
VerifyCode	string	The TXT record value for domain validation.	verify_16ab7f4d389d4dff6655f995c6a997bd
SslFlag	string	The SSL switch. on: Enabled. off: Disabled.	on
CertType	string	The certificate type. free: Free certificate. upload: Uploaded certificate. cas: Alibaba Cloud Security certificate.	free
CasId	integer	The ID of the Alibaba Cloud Security certificate.	30000478
CertId	string	The certificate ID.	baba2c9e90e840b3b55698cedf02b308
Certificate	string	The content of the certificate.	-----BEGIN CERTIFICATE-----
CertStatus	string	The status of the certificate. OK: Normal. Applying: The request is being processed. ApplyFailed: The request failed. Expiring: The certificate is about to expire. Expired: The certificate has expired.	OK
CertTxtKey	string	The TXT record name for certificate validation.	_acme-challenge.custom.site.com
CertTxtValue	string	The TXT record value for certificate validation.	lcKYad3UQXgrZLvMm_6TBUYKK4xTkGmninV0Mzx4gjM
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
CertNotAfter	string	The expiration time of the certificate. The date is in the ISO 8601 format and is in UTC. The format is `yyyy-MM-ddTHH:mm:ssZ`.	2026-04-19T11:15:20Z
CertApplyMessage	string	The error description for the free certificate request.	canceled
CertApplyCode	integer	The error code for the free certificate request.	2
CreateTime	string	The time when the SaaS domain name was created. The date is in the ISO 8601 format and is in UTC. The format is `yyyy-MM-ddTHH:mm:ssZ`.	2026-04-19T11:15:20Z
UpdateTime	string	The time when the SaaS domain name was last updated. The date is in the ISO 8601 format and is in UTC. The format is `yyyy-MM-ddTHH:mm:ssZ`.	2026-04-19T11:15:20Z
OfflineReason	string	The reason why the SaaS domain name is offline. expiration_arrears: The subscription expired or the account has an overdue payment. internally_disabled: Disabled by the system. missing_icp: The domain name is missing an ICP filing. content_violation: Content violation. proactively_disabled: The domain name was disabled manually or because it reached the usage cap.	missing_icp
ConflictWith	string	The reason why the SaaS domain name is in use. 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
PrivateKey	string	The private key of the certificate.	-----BEGIN RSA PRIVATE KEY-----

Examples

Success response

JSON format

{
  "RequestId": "7C414690-9D7B-5D66-9CD9-AD0B3F25ED49",
  "CustomHostnameModel": {
    "HostnameId": 1234567890123,
    "Hostname": "custom.site.com",
    "SiteId": 890601022130656,
    "SiteName": "example.com",
    "RecordId": 4042843419650112,
    "RecordName": "origin.example.com",
    "Status": "active",
    "VerifyHost": "_esa_custom_hostname.custom.site.com",
    "VerifyCode": "verify_16ab7f4d389d4dff6655f995c6a997bd",
    "SslFlag": "on",
    "CertType": "free",
    "CasId": 30000478,
    "CertId": "baba2c9e90e840b3b55698cedf02b308",
    "Certificate": "-----BEGIN CERTIFICATE-----",
    "CertStatus": "OK",
    "CertTxtKey": "_acme-challenge.custom.site.com",
    "CertTxtValue": "lcKYad3UQXgrZLvMm_6TBUYKK4xTkGmninV0Mzx4gjM",
    "CertHttpKey": "http://custom.site.com/.well-known/acme-challenge/jLmMHlEaZ3jb352Qo3ciaSoAC8KZ5Hk0F-4_1xLQtgc",
    "CertHttpValue": "jLmMHlEaZ3jb352Qo3ciaSoAC8KZ5Hk0F-4_1xLQtgc.GridYdfJJB5PgFEL-t89XfaFvMPB4f2-I9fwLpKl6e0",
    "CertNotAfter": "2026-04-19T11:15:20Z",
    "CertApplyMessage": "canceled",
    "CertApplyCode": 2,
    "CreateTime": "2026-04-19T11:15:20Z",
    "UpdateTime": "2026-04-19T11:15:20Z",
    "OfflineReason": "missing_icp",
    "ConflictWith": "existing_custom_hostname",
    "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----"
  }
}

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.