All Products
Search

This Product

    Server Load Balancer:DescribeLoadBalancerHTTPListenerAttribute

    Document Center

    Server Load Balancer:DescribeLoadBalancerHTTPListenerAttribute

    Last Updated:Mar 19, 2026

    Queries the configurations of an HTTP listener.

    Operation description

    Before you begin

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

    get

    *loadbalancer

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

    • slb:tag

    • slb:tag

    • slb:tag

    • slb:tag

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    RegionId

    string

    No

    The region ID of the CLB instance.

    Call the DescribeRegions operation to query the most recent region list.

    cn-hangzhou

    LoadBalancerId

    string

    Yes

    The CLB instance ID.

    lb-bp1uaunez0uho0zf0****

    ListenerPort

    integer

    Yes

    The frontend port that is used by the CLB instance.

    Valid values: 1 to 65535.

    80

    Response elements

    Element

    Type

    Description

    Example

    object

    AclType

    string

    The type of the ACL. Valid values:

    • white: a whitelist. Only requests from the IP addresses or CIDR blocks in the ACL are forwarded. Whitelists apply to scenarios where you want to allow only specific IP addresses to access an application. Your service may be adversely affected if the whitelist is not properly configured. If a whitelist is configured, only requests from IP addresses that are added to the whitelist are forwarded by the listener.

    If you enable a whitelist but do not add an IP address to the ACL, the listener forwards all requests.

    • black: a blacklist. All requests from the IP addresses or CIDR blocks in the network ACL are rejected. Blacklists apply to scenarios where you want to block access from specified IP addresses to an application.

    If a blacklist is configured for a listener but no IP address is added to the blacklist, the listener forwards all requests.

    Note

    This parameter is required when AclStatus is set to on.

    white

    VServerGroupId

    string

    The ID of the associated server group.

    rsp-cige6j****

    Status

    string

    The status of the listener. Valid values:

    • running: The listener is running normally.

    • stopped: The listener is stopped.

    stopped

    XForwardedFor_ClientSrcPort

    string

    Indicates whether the XForwardedFor_ClientSrcPort header is used to retrieve the client port. Valid values:

    • on

    • off

    off

    Cookie

    string

    The cookie that is configured on the server.

    testCookie

    Gzip

    string

    Indicates whether Gzip compression is enabled to compress specific types of files. Valid values:

    • on

    • off

    on

    HealthCheckConnectPort

    integer

    The port that is used for health checks.

    Note

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

    8080

    RequestId

    string

    The request ID.

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

    Description

    string

    The name of the listener.

    HTTP_80

    Bandwidth

    integer

    The maximum bandwidth of the listener. Unit: Mbit/s.

    • -1: If -1 is returned, it indicates that the bandwidth of the listener is unlimited.

    • 1 to 5120: If a value from 1 to 5120 is returned, the value indicates the maximum bandwidth of the listener. The sum of the maximum bandwidth of all listeners added to a CLB instance does not exceed the maximum bandwidth of the CLB instance.

    -1

    HealthCheckTimeout

    integer

    The timeout period of each health check. Unit: seconds.

    3

    AclStatus

    string

    Indicates whether access control is enabled. Valid values:

    • on

    • off

    off

    BackendServerPort

    integer

    The backend port that is used by the CLB instance.

    80

    CookieTimeout

    integer

    The timeout period of a cookie. Unit: seconds.

    500

    HealthCheckDomain

    string

    The domain name that you want to use for health checks.

    www.domain.com

    UnhealthyThreshold

    integer

    The unhealthy threshold.

    4

    ForwardPort

    integer

    The listener port that is used to redirect HTTP requests to HTTPS.

    Note

    If the ListenerForward parameter is set to off, this parameter is not displayed.

    80

    XForwardedFor_SLBID

    string

    Indicates whether the SLB-ID header is used to retrieve the ID of the CLB instance. Valid values:

    • on

    • off

    on

    SecurityStatus

    string

    Indicates whether the listener is in the Secure state. Valid values:

    • on

    • off

    on

    HealthCheckHttpCode

    string

    The HTTP status code for a successful health check.

    http_2xx,http_3xx

    ListenerForward

    string

    Indicates whether HTTP-to-HTTPS redirection is enabled. Valid values:

    • on

    • off

    on

    XForwardedFor

    string

    Indicates whether the X-Forwarded-For header is used to preserve the real IP address of the client. Valid values:

    • on

    • off

    on

    IdleTimeout

    integer

    The timeout period of an idle connection. Unit: seconds.

    Default value: 15. Valid values: 1 to 60.

    If no request is received within the specified timeout period, CLB closes the connection. When a request is received, CLB establishes a new connection.

    2

    RequestTimeout

    integer

    The timeout period of a request. Unit: seconds.

    Default value: 60. Valid values: 1 to 180.

    If no response is received from a backend server within the specified timeout period, CLB returns the HTTP 504 status code to the client.

    34

    ListenerPort

    integer

    The frontend port that is used by the CLB instance.

    80

    HealthCheckInterval

    integer

    The interval at which health checks are performed. Unit: seconds.

    5

    XForwardedFor_SLBPORT

    string

    Indicates whether the XForwardedFor_SLBPORT header is used to retrieve the listener port of the CLB instance. Valid values:

    • on

    • off

    off

    HealthCheckURI

    string

    The URL path that is used for health checks.

    The URI must be 1 to 80 characters in length, and can contain only digits, letters, hyphens (-), forward slashes (/), periods (.), percent signs (%), question marks (?), number signs (#), and ampersands (&). The URI must start with a forward slash (/) but cannot be a single forward slash (/).

    /test/index.html

    StickySessionType

    string

    The method that is used to handle a cookie.

    Valid values: insert and server.

    • insert: inserts a cookie.

      CLB inserts a session cookie (SERVERID) into the first HTTP or HTTPS response that is sent to a client. Subsequent requests to CLB carry this cookie, and CLB determines the destination servers of the requests based on the cookies.

    • server: rewrites a cookie.

      When CLB detects a user-defined cookie, it overwrites the original cookie with the user-defined cookie. The next request from the client carries the user-defined cookie, and the listener forwards this request to the recorded backend server.

    Note

    This parameter is required when StickySession is set to on.

    insert

    AclId

    string

    The ID of the network ACL that is associated with a listener.

    Note

    This parameter is returned when AclStatus is set to on.

    acl-uf60jw******

    Scheduler

    string

    The routing algorithm. Valid values:

    • wrr: Backend servers that have higher weights receive more requests than backend servers that have lower weights.

    • rr: Requests are sequentially distributed to backend servers.

    wrr

    HealthyThreshold

    integer

    The healthy threshold.

    4

    XForwardedFor_proto

    string

    Indicates whether the X-Forwarded-Proto header is used to retrieve the listener protocol. Valid values:

    • on

    • off

    on

    XForwardedFor_SLBIP

    string

    Indicates whether the SLB-IP header is used to retrieve the virtual IP address requested by the client. Valid values:

    • on

    • off

    on

    StickySession

    string

    Indicates whether session persistence is enabled. Valid values:

    • on

    • off

    on

    HealthCheckMethod

    string

    The health check method used by HTTP listeners. Valid values: head and get.

    Note

    This parameter is returned when HealthCheck is set to on.

    get

    HealthCheck

    string

    Indicates whether the health check feature is enabled. Valid values:

    • on

    • off

    on

    AclIds

    object

    AclId

    array

    The ID of the access control list (ACL).

    Rules

    object

    Rule

    array<object>

    The list of forwarding rules.

    object

    VServerGroupId

    string

    The ID of the server group specified in the forwarding rule.

    rsp-uf6w******

    Url

    string

    The request URL.

    /example

    Domain

    string

    The domain name.

    www.example.com

    RuleName

    string

    The name of the forwarding rule.

    test

    RuleId

    string

    The ID of the forwarding rule.

    1234

    LoadBalancerId

    string

    The CLB instance ID.

    lb-bp1uaunez0uho0zf0****

    Tags

    object

    Tag

    array<object>

    The tags.

    object

    The tags.

    TagKey

    string

    The key of tag N. Valid values of N: 1 to 20. The tag value cannot be an empty string. The tag key can be up to 64 characters in length. The key cannot start with acs: or aliyun or contain http:// or https://.

    TestKey

    TagValue

    string

    The value of tag N. Valid values of N: 1 to 20. The tag value can be an empty string. The tag value can be up to 128 characters in length, and cannot start with acs:. It cannot contain http:// or https://.

    TestValue

    Examples

    Success response

    JSON format

    {
  "AclType": "white",
  "VServerGroupId": "rsp-cige6j****",
  "Status": "stopped",
  "XForwardedFor_ClientSrcPort": "off",
  "Cookie": "testCookie",
  "Gzip": "on",
  "HealthCheckConnectPort": 8080,
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF34B540710",
  "Description": "HTTP_80",
  "Bandwidth": -1,
  "HealthCheckTimeout": 3,
  "AclStatus": "off",
  "BackendServerPort": 80,
  "CookieTimeout": 500,
  "HealthCheckDomain": "www.domain.com",
  "UnhealthyThreshold": 4,
  "ForwardPort": 80,
  "XForwardedFor_SLBID": "on",
  "SecurityStatus": "on",
  "HealthCheckHttpCode": "http_2xx,http_3xx",
  "ListenerForward": "on",
  "XForwardedFor": "on",
  "IdleTimeout": 2,
  "RequestTimeout": 34,
  "ListenerPort": 80,
  "HealthCheckInterval": 5,
  "XForwardedFor_SLBPORT": "off",
  "HealthCheckURI": "/test/index.html",
  "StickySessionType": "insert ",
  "AclId": "acl-uf60jw******",
  "Scheduler": "wrr",
  "HealthyThreshold": 4,
  "XForwardedFor_proto": "on",
  "XForwardedFor_SLBIP": "on",
  "StickySession": "on",
  "HealthCheckMethod": "get",
  "HealthCheck": "on",
  "AclIds": {
    "AclId": [
      ""
    ]
  },
  "Rules": {
    "Rule": [
      {
        "VServerGroupId": "rsp-uf6w******",
        "Url": "/example",
        "Domain": "www.example.com",
        "RuleName": "test",
        "RuleId": "1234"
      }
    ]
  },
  "LoadBalancerId": "lb-bp1uaunez0uho0zf0****",
  "Tags": {
    "Tag": [
      {
        "TagKey": "TestKey",
        "TagValue": "TestValue"
      }
    ]
  }
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.