All Products
Search

This Product

    Edge Security Acceleration:GetCustomHostname

    Document Center

    Edge Security Acceleration:GetCustomHostname

    Last Updated:Jun 25, 2026

    Retrieves the detailed configuration of a single SaaS domain name, including the domain verification TXT name, domain verification TXT content, and 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

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    esa:GetCustomHostname

    get

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    HostnameId

    integer

    Yes

    The ID of the SaaS domain name. You can obtain this value by calling the ListCustomHostnames operation.

    1234567890123

    Response elements

    Element

    Type

    Description

    Example

    object

    RequestId

    string

    The request ID, which is a unique identifier generated by Alibaba Cloud for this request.

    7C414690-9D7B-5D66-9CD9-AD0B3F25ED49
    CustomHostnameModel

    object

    The information about the queried 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. Valid values:

    • pending: Pending verification.

    • active: Activated.

    • conflicted: Occupied.

    • offline: Offline.

    • configuring: Being configured.

    Valid values:

    • conflicted :

      Occupied.

    • offline :

      Offline.

    • configuring :

      Being configured.

    • pending :

      Pending verification.

    • active :

      Activated.

    active
    VerifyHost

    string

    The TXT name for domain verification.

    _esa_custom_hostname.custom.site.com
    VerifyCode

    string

    The TXT content for domain verification.

    verify_16ab7f4d389d4dff6655f995c6a997bd
    SslFlag

    string

    The SSL switch. Valid values:

    • on: SSL is enabled.

    • off: SSL is disabled.

    Valid values:

    • off :

      SSL is disabled.

    • on :

      SSL is enabled.

    on
    CertType

    string

    The certificate type. Valid values:

    • free: Free certificate.

    • upload: Uploaded certificate.

    • cas: SSL Certificates Service certificate.

    Valid values:

    • cas :

      SSL Certificates Service certificate.

    • upload :

      Uploaded certificate.

    • free :

      Free certificate.

    free
    CasId

    integer

    The SSL Certificates Service certificate ID.

    30000478
    CertId

    string

    The certificate ID.

    baba2c9e90e840b3b55698cedf02b308
    Certificate

    string

    The certificate content.

    -----BEGIN CERTIFICATE-----
    CertStatus

    string

    The certificate status. Valid values:

    • OK: Normal.

    • Applying: Being applied.

    • ApplyFailed: Application failed.

    • Expiring: About to expire.

    • Expired: Expired.

    Valid values:

    • Expiring :

      About to expire.

    • ApplyFailed :

      Application failed.

    • Expired :

      Expired.

    • Applying :

      Being applied.

    • OK :

      Normal.

    OK
    CertTxtKey

    string

    The TXT name for certificate verification.

    _acme-challenge.custom.site.com
    CertTxtValue

    string

    The TXT content for certificate verification.

    lcKYad3UQXgrZLvMm_6TBUYKK4xTkGmninV0Mzx4gjM
    CertHttpKey

    string

    The HTTP address for certificate verification.

    http://custom.site.com/.well-known/acme-challenge/jLmMHlEaZ3jb352Qo3ciaSoAC8KZ5Hk0F-4_1xLQtgc
    CertHttpValue

    string

    The HTTP content for certificate verification.

    jLmMHlEaZ3jb352Qo3ciaSoAC8KZ5Hk0F-4_1xLQtgc.GridYdfJJB5PgFEL-t89XfaFvMPB4f2-I9fwLpKl6e0
    CertNotAfter

    string

    The certificate expiration time, in ISO 8601 format with UTC time. The format is yyyy-MM-ddTHH:mm:ssZ.

    2026-04-19T11:15:20Z
    CertApplyMessage

    string

    The error message for the free certificate application.

    canceled
    CertApplyCode

    integer

    The error code for the free certificate application.

    2
    CreateTime

    string

    The time when the SaaS domain name was created, in ISO 8601 format with UTC time. 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, in ISO 8601 format with UTC time. The format is yyyy-MM-ddTHH:mm:ssZ.

    2026-04-19T11:15:20Z
    OfflineReason

    string

    The reason why the SaaS domain name was taken offline. Valid values:

    • expiration_arrears: The subscription plan expired or the account has an overdue payment.

    • internally_disabled: Disabled by the system.

    • missing_icp: The domain name does not have an ICP filing.

    • content_violation: Content violation.

    • proactively_disabled: You proactively disabled the domain name or the usage cap you configured was reached.

    Valid values:

    • expiration_arrears :

      The subscription plan expired or the account has an overdue payment.

    • proactively_disabled :

      Proactively disabled or usage cap reached.

    • content_violation :

      Content violation.

    • internally_disabled :

      Disabled by the system.

    • missing_icp :

      The domain name does not have an ICP filing.

    missing_icp
    ConflictWith

    string

    The reason why the SaaS domain name is occupied. Valid values:

    • 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 balancing instance.

    • existing_origin_pool: Conflicts with an existing origin IPAM pool.

    • existing_site: Conflicts with an existing site.

    Valid values:

    • existing_load_balancer :

      Conflicts with an existing load balancing instance.

    • existing_custom_hostname :

      Conflicts with an existing SaaS domain name.

    • existing_site :

      Conflicts with an existing site.

    • existing_record :

      Conflicts with an existing site record.

    • 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.