All Products
Search

This Product

    Server Load Balancer:DescribeLoadBalancerListeners - List SLB listeners

    Document Center

    Server Load Balancer:DescribeLoadBalancerListeners - List SLB listeners

    Last Updated:Mar 03, 2026

    Lists details of Server Load Balancer (SLB) listeners.

    Operation description

    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

    slb:DescribeLoadBalancerListeners

    get

    *LoadBalancer

    acs:slb:{#regionId}:{#accountId}:loadbalancer/{#LoadBalancerId}

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    No

    The region ID of the Classic Load Balancer instance.

    You can call the DescribeRegions operation to query region IDs.

    Note

    If the endpoint of the selected region is slb.aliyuncs.com, you must specify RegionId.

    cn-hangzhou
    NextToken

    string

    No

    The token used to retrieve the next page of results. Valid values:

    • Leave this parameter empty for the first query or if no further pages exist.

    • If a next page exists, set this parameter to the NextToken value returned in the previous API call.

    FFmyTO70tTpLG6I3FmYAXGKPd****
    MaxResults

    integer

    No

    The number of entries to return on each page.

    Valid values: 1 to 100. Default value: 20.

    50
    ListenerProtocol

    string

    No

    The protocol of the Classic Load Balancer listener. Valid values:

    • tcp

    • udp

    • http

    • https

    http
    LoadBalancerId

    array

    No

    The IDs of up to 10 Classic Load Balancer instances.

    Note

    For non-SDK calls, use the LoadBalancerId.N format to specify this parameter.

    lb-123wrwer

    string

    No

    The ID of a Classic Load Balancer instance.

    lb-uf6so8u4g35prnvsw****
    Tag

    array<object>

    No

    The list of tags.

    object

    No

    The list of tags.

    Key

    string

    No

    The tag key of the resource. Valid values for N: 1 to 20. If you specify this parameter, it cannot be an empty string.

    The key can be up to 64 characters in length and cannot start with aliyun or acs:, or contain http:// or https://.

    TestKey
    Value

    string

    No

    The tag value of the resource. You can specify up to 20 tag values. The value can be an empty string and supports a maximum of 128 characters. It cannot start with aliyun or acs:, and it cannot contain http:// or https://.

    TestValue
    ListenerPort

    integer

    No

    The listening port of the CLB instance.

    443
    Description

    string

    No

    The custom name of the listener.

    HTTPS_443

    Response elements

    Element

    Type

    Description

    Example

    object

    NextToken

    string

    The token used to retrieve the next page of results. Valid values:

    • If NextToken is empty, no further pages exist.

    • If NextToken has a value, it indicates the starting token for the next query.

    FFmyTO70tTpLG6I3FmYAXGKPd****
    RequestId

    string

    The request ID.

    365F4154-92F6-4AE4-92F8-7FF34B540710
    TotalCount

    integer

    The total number of entries that match the request conditions.

    10
    MaxResults

    integer

    The number of entries to return on each page.

    50
    Listeners

    array<object>

    The list of listeners for Classic Load Balancer instances.

    Note

    This parameter is not returned if no listeners are configured for the instance.

    array<object>

    The list of listeners for Classic Load Balancer instances.

    Note

    This parameter is not returned if no listeners are configured for the instance.

    AclType

    string

    The access control type. Valid values:

    • white: Only requests from IP addresses or CIDR blocks in the specified access control policy group are forwarded. Use a whitelist when you want to allow only specific IP addresses to access the listener. Using a whitelist carries business risks. After you configure a whitelist, only IP addresses in the whitelist can access the SLB listener.

    If you enable a whitelist but do not add any IP addresses to the access control policy group, the SLB listener forwards all requests.

    • black: Requests from IP addresses or CIDR blocks in the specified access control policy group are not forwarded. Use a blacklist when you want to deny access from specific IP addresses.

    If you enable a blacklist but do not add any IP addresses to the access control policy group, the SLB listener forwards all requests.

    white
    Status

    string

    The status of the listener. Valid values:

    • running: The listener is running normally.

    • stopped: The listener is stopped.

    running
    VServerGroupId

    string

    The ID of the vServer group associated with the listener.

    rsp-cige6j****
    ListenerProtocol

    string

    The protocol of the Classic Load Balancer listener.

    http
    LoadBalancerId

    string

    The ID of the Classic Load Balancer instance.

    lb-bp1b6c719dfa****
    ListenerPort

    integer

    The listening port.

    80
    AclId

    string

    The ID of the access control policy group.

    acl-a2do9e413e0spzasx****
    Scheduler

    string

    The scheduling algorithm. Valid values:

    • wrr: Backend servers with higher weights receive more requests.

    • rr: Requests are distributed to backend servers in sequence.

    • sch: Consistent hashing based on source IP addresses. Requests from the same source IP address are scheduled to the same backend server.

    • tch: Consistent hashing based on the four-tuple (source IP address, destination IP address, source port, and destination port). Requests in the same stream are scheduled to the same backend server.

    • qch: Consistent hashing based on QUIC Connection ID. Requests with the same QUIC Connection ID are scheduled to the same backend server.

    Note

    Only guaranteed-performance instances support the sch, tch, and qch consistent hashing algorithms.

    wrr
    Bandwidth

    integer

    The peak bandwidth of the listener. Unit: Mbps.

    -1
    Description

    string

    The description of the listener.

    test
    AclStatus

    string

    Indicates whether access control is enabled. Valid values:

    • on: Yes

    • off: No

    off
    BackendServerPort

    integer

    The port of the backend server.

    Note

    This parameter takes effect only when both VServerGroupId and MasterSlaveServerGroupId are empty.

    80
    AclIds

    array

    The list of access control policy group IDs.

    HTTPListenerConfig

    object

    The HTTP listener configuration.

    HealthCheckHttpVersion

    string

    The HTTP protocol version used for health checks.

    HTTP 1.0
    XForwardedFor_ClientSrcPort

    string

    Indicates whether to use the XForwardedFor_ClientSrcPort header to obtain the port of the client that accesses the SLB instance. Valid values:

    • on: Yes

    • off: No

    on
    Cookie

    string

    The cookie configured on the server.

    B490B5EBF6F3CD402E515D22BCDA****
    Gzip

    string

    Indicates whether to enable Gzip compression. Valid values:

    • on: Yes

    • off: No

    on
    HealthCheckConnectPort

    integer

    The port used for health checks.

    Note

    This parameter takes effect only when HealthCheck is set to on.

    8080
    HealthCheckTimeout

    integer

    The maximum timeout period for each health check response. Unit: seconds.

    3
    HealthCheckType

    string

    The health check protocol.

    tcp
    CookieTimeout

    integer

    The cookie timeout period. Unit: seconds.

    Valid values: 1 to 86400.

    500
    HealthCheckDomain

    string

    The domain name used for health checks.

    www.example.com
    UnhealthyThreshold

    integer

    The number of consecutive health check failures required before the health status of a backend server changes from success to failure.

    Valid values: 2 to 10.

    4
    XForwardedFor_SLBID

    string

    Indicates whether to use the SLB-ID header to obtain the SLB instance ID. Valid values:

    • on: Yes

    • off: No

    on
    ForwardPort

    integer

    The listening port to which HTTP requests are forwarded over HTTPS.

    Note

    This parameter is not displayed if ListenerForward is set to off.

    80
    HealthCheckHttpCode

    string

    The HTTP status code that indicates a successful health check.

    http_2xx,http_3xx
    ListenerForward

    string

    Indicates whether to enable HTTP-to-HTTPS forwarding. Valid values:

    • on: Yes

    • off: No

    on
    XForwardedFor

    string

    Indicates whether to use the XForwardedFor header to obtain the real IP address of the client. Valid values:

    • on: Yes.

    • off: No.

    on
    IdleTimeout

    integer

    The idle connection timeout period. Unit: seconds. Valid values: 1 to 60.

    If no request is received within the timeout period, SLB temporarily closes the current connection and re-establishes the connection when the next request arrives.

    15
    RequestTimeout

    integer

    The request timeout period. Unit: seconds. Valid values: 1 to 180.

    If the backend server does not respond within the timeout period, SLB stops waiting and returns an HTTP 504 error to the client.

    60
    HealthCheckInterval

    integer

    The interval between two consecutive health checks. Unit: seconds.

    5
    XForwardedFor_SLBPORT

    string

    Indicates whether to use the XForwardedFor_SLBPORT header to obtain the listening port of the SLB instance. Valid values:

    • on: Yes

    • off: No

    on
    HealthCheckURI

    string

    The URI used for health checks.

    /test/index.html
    StickySessionType

    string

    The method used to handle cookies. Valid values:

    • insert: Insert a cookie. When a client accesses SLB for the first time, SLB inserts a cookie (SERVERID) into the HTTP or HTTPS response. Subsequent requests carrying this cookie are forwarded to the same backend server.

    • server: Rewrite a cookie. If SLB detects a user-defined cookie, it rewrites the original cookie. Subsequent requests carrying the new cookie are forwarded to the same backend server.

    insert
    HealthyThreshold

    integer

    The number of consecutive successful health checks required before the health status of a backend server changes from failure to success.

    Valid values: 2 to 10.

    4
    XForwardedFor_proto

    string

    Indicates whether to use the X-Forwarded-Proto header to obtain the listening protocol of the SLB instance. Valid values:

    • on: Yes

    • off: No

    on
    XForwardedFor_SLBIP

    string

    Indicates whether to use the SLB-IP header to obtain the VIP (virtual IP address) of the client request. Valid values:

    • on: Yes

    • off: No

    on
    StickySession

    string

    Indicates whether to enable session persistence. Valid values:

    • on: Yes

    • off: No

    on
    HealthCheckMethod

    string

    The health check method. Valid values: head or get.

    get
    HealthCheck

    string

    Indicates whether to enable health checks. Valid values:

    • on: Yes

    • off: No

    on
    HTTPSListenerConfig

    object

    The HTTPS listener configuration.

    XForwardedFor_ClientCertClientVerify

    string

    Indicates whether to use the XForwardedFor_ClientCertClientVerify header to obtain the verification result of the client certificate. Valid values:

    • on: Yes

    • off: No

    off
    HealthCheckHttpVersion

    string

    The HTTP protocol version used for health checks.

    HTTP 1.0
    XForwardedFor_ClientSrcPort

    string

    Indicates whether to use the XForwardedFor_ClientSrcPort header to obtain the port of the client that accesses the SLB instance. Valid values:

    • on: Yes

    • off: No

    off
    Cookie

    string

    The cookie configured on the server.

    B490B5EBF6F3CD402E515D22BCDA****
    Gzip

    string

    Indicates whether to enable Gzip compression. Valid values:

    • on: Yes

    • off: No

    on
    EnableHttp2

    string

    Indicates whether to enable the HTTP 2.0 feature. Valid values:

    • on: Yes

    • off: No

    off
    CACertificateId

    string

    The ID of the CA certificate.

    idkp-234-cn-test-0****
    HealthCheckConnectPort

    integer

    The port used for health checks.

    8080
    HealthCheckTimeout

    integer

    The maximum timeout period for each health check response. Unit: seconds.

    3
    HealthCheckType

    string

    The health check protocol.

    tcp
    CookieTimeout

    integer

    The cookie timeout period. Unit: seconds.

    Valid values: 1 to 86400.

    500
    HealthCheckDomain

    string

    The domain name used for health checks.

    www.example.com
    UnhealthyThreshold

    integer

    The number of consecutive health check failures required before the health status of a backend server changes from success to failure.

    Valid values: 2 to 10.

    4
    XForwardedFor_SLBID

    string

    Indicates whether to use the SLB-ID header to obtain the SLB instance ID. Valid values:

    • on: Yes

    • off: No

    on
    XForwardedFor_ClientCertSubjectDN

    string

    Indicates whether to use the XForwardedFor_ClientCertSubjectDN header to obtain the subject DN of the client certificate. Valid values:

    • on: Yes.

    • off: No.

    off
    HealthCheckHttpCode

    string

    The HTTP status code that indicates a successful health check.

    http_2xx,http_3xx
    XForwardedFor_ClientCertFingerprint

    string

    Indicates whether to use the XForwardedFor_ClientCertFingerprint header to obtain the fingerprint of the client certificate. Valid values:

    • on: Yes

    • off: No

    off
    XForwardedFor

    string

    Indicates whether to use the XForwardedFor header to obtain the real IP address of the client. Valid values:

    • on: Yes

    • off: No

    on
    RequestTimeout

    integer

    The request timeout period. Unit: seconds. Valid values: 1 to 180.

    If the backend server does not respond within the timeout period, SLB stops waiting and returns an HTTP 504 error to the client.

    60
    IdleTimeout

    integer

    The idle connection timeout period. Unit: seconds. Valid values: 1 to 60.

    If no request is received within the timeout period, SLB temporarily closes the current connection and re-establishes the connection when the next request arrives.

    15
    ServerCertificateId

    string

    The ID of the server certificate.

    idkp-123-cn-test-0****
    HealthCheckInterval

    integer

    The interval between two consecutive health checks. Unit: seconds.

    5
    XForwardedFor_SLBPORT

    string

    Indicates whether to use the XForwardedFor_SLBPORT header to obtain the listening port of the SLB instance. Valid values:

    • on: Yes

    • off: No

    off
    HealthCheckURI

    string

    The URI used for health checks.

    /test/index.html
    StickySessionType

    string

    The method used to handle cookies.

    • insert: Insert a cookie. When a client accesses SLB for the first time, SLB inserts a cookie (SERVERID) into the HTTP or HTTPS response. Subsequent requests carrying this cookie are forwarded to the same backend server.

    • server: Rewrite a cookie. If SLB detects a user-defined cookie, it rewrites the original cookie. Subsequent requests carrying the new cookie are forwarded to the same backend server.

    insert
    XForwardedFor_ClientCertIssuerDN

    string

    Indicates whether to use the XForwardedFor_ClientCertIssuerDN header to obtain the issuer DN of the client certificate. Valid values:

    • on: Yes

    • off: No

    off
    HealthyThreshold

    integer

    The number of consecutive successful health checks required before the health status of a backend server changes from failure to success.

    Valid values: 2 to 10.

    4
    XForwardedFor_proto

    string

    Indicates whether to use the X-Forwarded-Proto header to obtain the listening protocol of the SLB instance. Valid values:

    • on: Yes

    • off: No

    on
    XForwardedFor_SLBIP

    string

    Indicates whether to use the SLB-IP header to obtain the VIP (virtual IP address) of the client request. Valid values:

    • on: Yes

    • off: No

    on
    StickySession

    string

    Indicates whether to enable session persistence. Valid values:

    • on: Yes

    • off: No

    on
    HealthCheckMethod

    string

    The health check method.

    get
    TLSCipherPolicy

    string

    The security policy that defines the TLS protocol versions and cipher suites supported by HTTPS.

    • tls_cipher_policy_1_0:

      Supported TLS versions: TLSv1.0, TLSv1.1, and TLSv1.2.

      Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.

    • tls_cipher_policy_1_1:

      Supported TLS versions: TLSv1.1 and TLSv1.2.

      Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.

    • tls_cipher_policy_1_2

      Supported TLS version: TLSv1.2.

      Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.

    • tls_cipher_policy_1_2_strict

      Supported TLS version: TLSv1.2.

      Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, ECDHE-RSA-AES128-SHA, and ECDHE-RSA-AES256-SHA.

    • tls_cipher_policy_1_2_strict_with_1_3

      Supported TLS versions: TLSv1.2 and TLSv1.3.

      Supported cipher suites: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, TLS_AES_128_CCM_8_SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES128-SHA256, ECDHE-ECDSA-AES256-SHA384, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, ECDHE-ECDSA-AES128-SHA, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES128-SHA, and ECDHE-RSA-AES256-SHA.

    tls_cipher_policy_1_0
    HealthCheck

    string

    Indicates whether to enable health checks. Valid values:

    • on: Yes.

    • off: No.

    on
    TCPListenerConfig

    object

    The TCP listener configuration.

    HealthCheckHttpCode

    string

    The HTTP status code that indicates a successful health check.

    http_2xx,http_3xx
    ConnectionDrainTimeout

    integer

    The timeout period for connection draining. Unit: seconds.

    Valid values: 10 to 900.

    300
    PersistenceTimeout

    integer

    Indicates whether session persistence is enabled. Unit: seconds.

    Valid values: 0 to 3600.

    A value of 0 indicates that session persistence is disabled.

    0
    HealthCheckInterval

    integer

    The interval between two consecutive health checks. Unit: seconds.

    5
    HealthCheckURI

    string

    The URI used for health checks.

    /test/index.html
    HealthCheckConnectPort

    integer

    The port used for health checks.

    8080
    EstablishedTimeout

    integer

    The connection timeout period. Unit: seconds.

    500
    HealthCheckType

    string

    The health check protocol.

    tcp
    HealthCheckConnectTimeout

    integer

    The health check timeout period. Unit: seconds.

    Valid values: 1 to 300.

    100
    MasterSlaveServerGroupId

    string

    The ID of the primary/secondary server group associated with the listener.

    rsp-0bfucw*****
    HealthyThreshold

    integer

    The number of consecutive successful health checks required before the health status of a backend server changes from failure to success.

    Valid values: 2 to 10.

    4
    HealthCheckDomain

    string

    The domain name used for health checks.

    www.example.com
    UnhealthyThreshold

    integer

    The number of consecutive health check failures required before the health status of a backend server changes from success to failure.

    Valid values: 2 to 10.

    4
    ConnectionDrain

    string

    Indicates whether to enable connection draining. Valid values:

    • on: Yes

    • off: No

    off
    HealthCheckMethod

    string

    The health check method.

    get
    HealthCheck

    string

    Indicates whether to enable health checks. Valid values:

    • on: Yes

    • off: No

    on
    ProxyProtocolV2Enabled

    string

    Indicates whether to use the Proxy Protocol to pass the client source IP address to backend servers. Valid values:

    • true: Yes.

    • false: No.

    false
    UDPListenerConfig

    object

    The UDP listener configuration.

    ConnectionDrainTimeout

    integer

    The timeout period for connection draining. Unit: seconds.

    Valid values: 10 to 900.

    300
    HealthCheckInterval

    integer

    The interval between two consecutive health checks. Unit: seconds.

    5
    HealthCheckExp

    string

    The expected response string for UDP health checks.

    ok
    HealthCheckConnectPort

    integer

    The port used for health checks.

    8080
    HealthCheckConnectTimeout

    integer

    The health check response timeout period.

    100
    MasterSlaveServerGroupId

    string

    The ID of the primary/secondary server group.

    rsp-0bfucw****
    HealthyThreshold

    integer

    The healthy threshold for health checks.

    4
    UnhealthyThreshold

    integer

    The unhealthy threshold for health checks.

    4
    ConnectionDrain

    string

    Indicates whether to enable connection draining. Valid values:

    • on: Yes

    • off: No

    off
    HealthCheckReq

    string

    The request string for UDP health checks.

    hello
    HealthCheck

    string

    Indicates whether to enable health checks. Valid values:

    • on: Yes

    • off: No

    on
    ProxyProtocolV2Enabled

    string

    Indicates whether to use the Proxy Protocol to pass the client source IP address to backend servers. Valid values:

    • true: Yes.

    • false: No.

    false
    Tags

    array<object>

    The list of tags.

    object

    The list of tags.

    TagValue

    string

    The tag value of the resource.

    TestValue
    TagKey

    string

    The tag key of the resource.

    TestKey

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 IllegalParam.ListenerProtocol The param of ListenerProtocol is illegal. The specified ListenerProtocol is invalid. Check the parameter constraints and try again.
    400 IllegalParam.MaxResults The param of MaxResults is illegal. The specified MaxResults is invalid. Check the parameter constraints and try again.
    400 IllegalParam.NextToken The param of NextToken is illegal. The specified NextToken is invalid. Check the parameter constraints and try again.
    400 IllegalParamSize.LoadBalancerId The param size of LoadBalancerId is illegal. The specified LoadBalancerId is invalid. Check the parameter constraints and try again.
    400 MissingParam.TagKey The param of TagKey is missing.
    403 UnauthorizedRegion The specified region of is not authorized. The specified region is not visible.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.