All Products
Search

This Product

    Edge Security Acceleration:ListCustomHostnames

    Document Center

    Edge Security Acceleration:ListCustomHostnames

    Last Updated:Jun 25, 2026

    Queries the list of SaaS domain names under a site, including the ID, status, and domain name verification information of each SaaS domain name. You can filter results by SaaS domain name, site ID, or associated record ID.

    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:ListCustomHostnames

    list

    *Site

    acs:esa:{#regionId}:{#accountId}:site/{#SiteId}

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    SiteId

    integer

    Yes

    The site ID. You can call the ListSites operation to obtain the site ID.

    744571165985008
    RecordId

    integer

    No

    The associated record ID. You can call the ListRecords operation to obtain the record ID.

    1234567890123
    Hostname

    string

    No

    The SaaS domain name.

    custom.site.com
    NameMatchType

    string

    No

    The search match mode for the SaaS domain name. Default value: exact. Valid values:

    • prefix: prefix match.

    • suffix: suffix match.

    • exact: exact match.

    • fuzzy: fuzzy match.

    Valid values:

    • prefix :

      Prefix match.

    • exact :

      Exact match.

    • suffix :

      Suffix match.

    • fuzzy :

      Fuzzy match.

    exact
    Status

    string

    No

    The SaaS domain name status. Valid values:

    • pending: pending verification.

    • active: activated.

    • conflicted: occupied.

    • offline: offline.

    Valid values:

    • conflicted :

      Occupied.

    • offline :

      Offline.

    • pending :

      Pending verification.

    • active :

      Activated.

    active
    PageNumber

    integer

    No

    The page number for a paged query. The value must be greater than or equal to 1.

    1
    PageSize

    integer

    No

    The number of entries per page for a paged query. Valid values: 1 to 500.

    500

    Response elements

    Element

    Type

    Description

    Example

    object

    RequestId

    string

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

    04F0F334-1335-436C-A1D7-6C044FE73368
    PageNumber

    integer

    The current page number. This value is the same as the PageNumber request parameter.

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

    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 SaaS domain name status. 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
    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
    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
    CertTxtKey

    string

    The TXT record name for certificate verification.

    _acme-challenge.custom.site.com

    CertTxtValue

    string

    The TXT record content for certificate verification.

    lcKYad3UQXgrZLvMm_6TBUYKK4xTkGmninV0Mzx4gjM

    VerifyHost

    string

    The TXT record name for domain name verification.

    _esa_custom_hostname.custom.site.com

    VerifyCode

    string

    The TXT record content for domain name verification.

    verify_16ab7f4d389d4dff6655f995c6a997bd

    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
    CertNotAfter

    string

    The certificate expiration time, in the ISO 8601 standard in UTC. Format: 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

    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: proactively disabled by you or disabled because 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 by you or disabled because the usage cap was 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_site: conflicts with an existing site.

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

    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
    CreateTime

    string

    The creation time of the SaaS domain name, in the ISO 8601 standard in UTC. Format: yyyy-MM-ddTHH:mm:ssZ.

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

    string

    The update time of the SaaS domain name, in the ISO 8601 standard in UTC. Format: 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.