Load Balancer
Load Balancer
Document
- Documentation
Load BalancerClassic Load Balancer (CLB)API referenceListenerDescribeListeners - Querying a listener list
Copy page
Download PDFListener
DescribeListeners - Querying a listener list
Copy pageDownload PDFDescribeListeners - Querying a listener list
Call the DescribeListeners API to query listeners that meet the specified conditions.
Instructions
- If multiple request parameters are provided, the query will return listener entries that match all the specified conditions. If no matching entry is found, an empty value is returned.
- If none of the optional request parameters are provided, the query will be performed under the current logged-in account and return all listeners belonging to this account.
Debug
API Explorer
You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.
Request parameters
Action String required Example: DescribeListeners
Action to execute. Set the value to DescribeListeners.
Version String required Example: 2020-04-01
API version. The current version is 2020-04-01.
LoadBalancerId String optional Example: clb-bp1o94dp5i6ea****
CLB instance ID.
ListenerIds.N String optional Example: lsn-2fek3rgsxhrsw5oxr****
Listener ID.
- Parameter - N: Indicates the serial number of the listener. Value range: 1 to 100.
- Separate listener IDs with ampersands (&).
ListenerName String optional Example: mylistener
Listener name.
Protocol String optional Example: TCP
The protocol of the listener.
- TCP
- UDP
- HTTP
- HTTPS
TagFilters.N.Key String optional Example: k1
The tag key.
- N represents the sequence number of a tag key. Values: 1-10.
- Separate multiple tag keys with &. Multiple tag keys have a logical AND relationship. The query returns listeners tagged with all the specified keys.
TagFilters.N.Values.N String optional Example: v1
The tag value.
- The first N represents the sequence number of a tag key.
- The second N represents the sequence number of a tag value. Valid values: 1–3. Multiple tag values under the same tag key are combined using a logical OR operation, meaning the query returns listeners that have any of the specified tag values for that key.
- Separate multiple tag values with ampersands (&).
tip
- If this parameter is passed in, TagFilters.N.Key must be passed in first.
- Passing an empty string queries for listeners with an empty tag value.
PageNumber Integer optional Example: 1
The page number of the list. Default: 1.
PageSize Integer optional Example: 20
The number of rows per page for paginated queries. Valid range: 1-100. Default value: 10.
Response parameters
RequestId String Example: 20210811152539010225146063030****
Request ID
TotalCount Integer Example: 50
Total number of matching listeners.
PageNumber Integer Example: 1
Current page number.
PageSize Integer Example: 20
The number of rows on the current page.
Listeners Object[] Example: -
Detailed information of listeners that meet the criteria.
LoadBalancerId String Example: clb-bp1o94dp5i6ea****
CLB instance ID.
ListenerId String Example: lsn-2fek3rgsxhrsw5oxruwec****
Listener ID.
ListenerName String Example: listener-1
Listener name.
Description String Example: mylistener
Description of the listener.
Protocol String Example: TCP
Listener protocol.
Port Integer Example: 80
Listening port.
- 0: Enable full port listening. Full port listening is currently in beta stage. For trial requests, contact your account manager.
- Other ports: Specific listening ports.
StartPort Integer Example: 80
Start port for full port listening.
This parameter is returned only when full port listening is enabled.
End port Integer Example: 100
End port for full port monitoring.
This parameter is returned only when full port listening is enabled.
Scheduler String Example: wrr
The scheduling algorithm used by the listener.
- wrr (Weighted Round Robin): A load balancing algorithm where backend servers with higher weights values receive more frequent polling attempts (higher probability).
- wlc (Weighted Least Connection): This method maintains minimum connections and assigns a weight to each server based on its processing capacities of the server. Servers with higher weights receive a proportionally larger share of incoming requests.
- sh (Source address hashing): A consistency hash based on the Source IP address, allowing the same source to be scheduled to the same backend server.
Cps Integer Example: 10
The maximum number of new connections per second for the listener.
MaxConnections Integer Example: 10
The maximum number of max connections for the listener.
Bandwidth Integer Example: 10
The peak bandwidth of the listener. Unit: Mbps
Returns -1, indicating that the listener does not have a rate limit specified. In this case, the bandwidth peak of the listener defaults to the remaining bandwidth of the CLB instance specification.
ServerGroupId String Example: rsp-bp1o94dp5i6ea****
The ID of the backend server group associated with the TCP/UDP listener. The default backend server group ID associated with the HTTP/HTTPS listener.
CertificateSource String Example: clb
Certificate source.
- clb: CLB certificate management module.
- cert_center: Certificate Center.
CertCenterCertificateId String Example: cert-bp1o94dp5i6eb****
Certificate ID from the Certificate Center.
CertificateId String Example: cert-bp1o94dp5i6ea****
The certificate ID from the CLB Certificate Management module.
CAEnabled String Example: off
Whether to enable mutual authentication.
- on: Enable.
- off: Disable.
CACertificateId String Example: pca_leaf_M6gaihuZRcO****
The CA certificate for mutual authentication.
HealthCheck Object Example: -
Health check parameters vary depending on the protocol.
Enabled String Example: off
Whether the health check feature is enabled for the listener.
- on: Enable.
- off: Disable.
UdpRequest String Example: Request123
The request string for performing health checks.
This parameter is returned only when a request string is specified for a UDP listener.
UdpExpect String Example: Expect123
Expected response string for health checks.
This parameter is returned only when a request string is specified for a UDP listener.
Interval Integer Example: 2
The time interval for performing health checks.
Timeout Integer Example: 2
The response timeout for health checks. If the backend server does not respond correctly within the specified time, it is considered "abnormal".
HealthyThreshold Integer Example: 3
The healthy threshold for health checks. If a backend server consecutively passes health checks for the specified number of times, it will be deemed normal.
UnHealthyThreshold Integer Example: 3
The unhealthy threshold for health checks. If a backend server consecutively fails health checks for the specified number of times, it will be deemed abnormal.
Method String Example: GET
Health check method of listeners.
- GET: The server must support the GET method.
- HEAD: The server returns only the HEAD header information, which reduces backend overhead but requires the server to support the HEAD method.
tip
This parameter is not returned for TCP/UDP listeners.
Uri String Example: /
Health check path.
tip
This parameter is not returned for TCP/UDP listeners.
Domain String Example: www.test.com
Health check domain name.
tip
This parameter is not returned for TCP/UDP listeners.
HttpCode String Example: http_2xx
The HTTP status code indicates a successful health check.
- http_2xx
- http_3xx
- http_4xx
- http_5xx
tip
This parameter is not returned for TCP/UDP listeners.
Port Integer Example: 80
Backend server port of health check.
- When full port listening is enabled, this parameter is returned to indicate the port used for health checks.
- When full port listening is not enabled, this parameter is not returned, and health checks use the service port of the backend server.
AclStatus String Example: off
Enable access control.
- on: Enable.
- off: Disable.
AclType String Example: black
Method of access control.
- white: Allowlist. When the listener listens to the traffic of the CLB, the CLB only forwards requests from IP addresses that are in the ACL associated with its allowlist.
- black: Denylist. When the listener listens to the traffic of the CLB, the CLB refuses to forward requests from IP addresses that are in the ACL associated with its allowlist.
tip
This is returned only when the AclStatus parameter is set to on.
AclIds String[] Example: ["acl-2fe5excqgk6ww5oxruvcv****","acl-2febxt4pu0zy85oxruw0t****"]
The ID of the ACL bound to the listener.
tip
This is returned only when the AclStatus parameter is set to on.
ProxyProtocolType String Example: off
Enable the Proxy-Protocol. Valid values:
- off: Disable.
- standard: Enable.
PersistenceType String Example: off
Session persistence type.
- off: Session persistence disabled.
- source_ip: Source IP address.
- insert: Implant cookie.
- server: Rewrite cookie.
PersistenceTimeout Integer Example: 10
Session persistence timeout, in seconds.
Cookie String Example: cookie123
The cookie name for session persistence configured on the backend server.
ClientHeaderTimeout Integer Example: 60
The timeout for reading the client_header_timeout. The client initiates a request to CLB. If the client does not transmit the entire header within the timeout period, CLB will return a 408 error code to the client, indicating a request timeout.
This parameter is returned only for HTTP/HTTPS listeners.
ClientBodyTimeout Integer Example: 60
The timeout for reading the client_body_timeout. The client initiates a request to CLB. If the client does not send any request body within the timeout period, CLB will return a 408 error code to the client, indicating a request timeout.
- This timeout applies only between two consecutive read operations, not to the entire request transmission.
- This parameter is returned only for HTTP/HTTPS listeners.
KeepaliveTimeout Integer Example: 60
Keepalive timeout between the client and the CLB. If there is no access request within the timeout period, CLB will interrupt the current connection and re-establish a new connection when the next request arrives.
- 0 indicates that keepalive is disabled.
- This parameter is returned only for HTTP/HTTPS listeners.
ProxyConnectTimeout Integer Example: 60
The connection establishment timeout between the CLB and a backend server. If the connection between CLB and the backend server is not established within the timeout period, the connection establishment operation is terminated.
This parameter is returned only for HTTP/HTTPS listeners.
ProxySendTimeout Integer Example: 60
The timeout period for the CLB to transmit a request to a backend server. CLB initiates a request to the backend server. If the backend server does not receive any content within the timeout period, it will close this connection.
- This timeout is set only between two consecutive write operations, not for the entire request transmission process.
- This parameter is returned only for HTTP/HTTPS listeners.
ProxyReadTimeout Integer Example: 60
The timeout for reading a response from the backend server. CLB initiates a request to the backend server. If the backend server that receives the request does not respond within the timeout period, this connection will be closed.
- This timeout applies only between two consecutive read operations, not to the entire response transmission.
- This parameter is returned only for HTTP/HTTPS listeners.
SendTimeout Integer Example: 60
The timeout period for the CLB to send a response to the client. CLB sends a response to the client. If the client does not receive any content within the timeout period, the connection will be closed.
- This timeout applies only between two consecutive write operations, not to the entire response transmission.
- This parameter is returned only for HTTP/HTTPS listeners.
SecurityPolicyId String Example: default_policy
TLS security policy for HTTPS listeners. This parameter is returned only for HTTPS listeners.
- default_policy: Supports SSL v3, TLS v1.0, TLS v1.1, TLS v1.2.
- tls_cipher_policy_1_0: Supports TLS v1.0, TLS v1.1, TLS v1.2.
- tls_cipher_policy_1_1: Supports TLS v1.1, TLS v1.2.
- tls_cipher_policy_1_2: Supports TLS v1.2.
- tls_cipher_policy_1_2_strict: Supports TLS v1.2.
tip
- For details on the cipher suites supported by the above TLS security policies except default_policy, see Creating an HTTPS protocol listener.
- When default_policy is passed, the configuration takes effect according to: ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5.
Http2Enabled String Example: off
Whether the HTTPS protocol listener enables the frontend HTTP/2.0 protocol.
- on: Enable.
- off: Disable.
tip
This parameter is not returned for TCP, UDP, and HTTP protocol listeners.
ConnectionDrainEnabled String Example: on
Listener enables Connection Drain feature.
- on: Enable.
- off: Disable.
tip
When the Protocol parameter returns HTTP or HTTPS, this parameter is fixed to return off.
ConnectionDrainTimeout Integer Example: 2
Timeout for connection draining, in seconds.
tip
When the parameter ConnectionDrainEnabled returns off, this parameter returns 0.
EstablishedTimeout Integer Example: 100
The connection timeout period of the listener.
Description: This parameter is returned only for TCP/UDP listeners.
Status String Example: Active
Listener status.
- Creating
- Active: Running.
- Deleting
- Disabled
Enabled String Example: off
Enable the listener.
- on: Enable.
- off: Disable.
WafProtectionEnabled String Example: off
Whether to send traffic passing through the layer‑7 listener to the Web Application Firewall for inspection and filtering.
- on: Yes.
- off: No.
Tags Object[] Example: -
Tag information.
Key String Example: k1
The tag key.
Value String Example: v1
The tag value.
CreateTime String Example: 2021-08-11T16:37:37Z
Creation time of listener.
UpdateTime String Example: 2021-08-11T16:37:37Z
Last operation time of the listener.
DomainExtensions Object[] Example: -
The list of additional domains associated with the eligible listener.
Domain String Example: www.test.com
Domain name.
CertificateSource String Example: cert_center
Certificate source.
- cert_center: SSL certificate from the VolcanoEngine Certificate Center.
DomainExtensionId String Example: de-***
Additional domain ID.
CertCenterCertificateId String Example: cert-***
Certificate ID.
Request examples
GET /?Action=DescribeListeners&Version=2020-04-01&LoadBalancerId=clb-bp1o94dp5i6ea****&ListenerIds.1=lsn-2fek3rgsxhrsw5oxr****&ListenerName=mylistener&Protocol=TCP&TagFilters.1.Key=k1&TagFilters.1.Values.1=v1&PageNumber=1&PageSize=20
Host: clb.cn-beijing.volcengineapi.com
X-Date: 20251121T094038Z
Authorization: HMAC-SHA256 Credential=Adfks******wekfwe/20251121/cn-beijing/clb/request, SignedHeaders=host;x-date, Signature=47a7d934ff7b37c03938******cd7b8278a40a1057690c401e92246a0e41085f
Response examples
{
"ResponseMetadata": {
"RequestId": "20230604110420****100232280022D31",
"Action": "DescribeListeners",
"Version": "2020-04-01",
"Service": "clb",
"Region": "cn-beijing"
},
"Result": {
"Listeners": [
{
"Cps": 10,
"Port": 80,
"Tags": [
{
"Key": "k1",
"Value": "v1"
}
],
"AclIds": [
"acl-2fe5excqgk6ww5oxruvcv****",
"acl-2febxt4pu0zy85oxruw0t****"
],
"Cookie": "cookie123",
"Status": "Active",
"AclType": "black",
"Enabled": "off",
"EndPort": 100,
"Protocol": "TCP",
"AclStatus": "off",
"Bandwidth": 10,
"CAEnabled": "off",
"Scheduler": "wrr",
"StartPort": 80,
"CreateTime": "2021-08-11T16:37:37Z",
"ListenerId": "lsn-2fek3rgsxhrsw5oxruwec****",
"UpdateTime": "2021-08-11T16:37:37Z",
"Description": "mylistener",
"HealthCheck": {
"Uri": "/",
"Port": 80,
"Domain": "www.test.com",
"Method": "GET",
"Enabled": "off",
"Timeout": 2,
"HttpCode": "http_2xx",
"Interval": 2,
"UdpExpect": "Expect123",
"UdpRequest": "Request123",
"HealthyThreshold": 3,
"UnHealthyThreshold": 3
},
"SendTimeout": 60,
"Http2Enabled": "off",
"ListenerName": "listener-1",
"CertificateId": "cert-bp1o94dp5i6ea****",
"ServerGroupId": "rsp-bp1o94dp5i6ea****",
"LoadBalancerId": "clb-bp1o94dp5i6ea****",
"MaxConnections": 10,
"CACertificateId": "pca_leaf_M6gaihuZRcO****",
"PersistenceType": "off",
"DomainExtensions": [
{
"Domain": "www.test.com",
"CertificateSource": "cert_center",
"DomainExtensionId": "de-***",
"CertCenterCertificateId": "cert-***"
}
],
"KeepaliveTimeout": 60,
"ProxyReadTimeout": 60,
"ProxySendTimeout": 60,
"SecurityPolicyId": "default_policy",
"CertificateSource": "clb",
"ClientBodyTimeout": 60,
"ProxyProtocolType": "off",
"EstablishedTimeout": 100,
"PersistenceTimeout": 10,
"ClientHeaderTimeout": 60,
"ProxyConnectTimeout": 60,
"WafProtectionEnabled": "off",
"ConnectionDrainEnabled": "on",
"ConnectionDrainTimeout": 2,
"CertCenterCertificateId": "cert-bp1o94dp5i6eb****"
}
],
"PageNumber": 1,
"PageSize": 20,
"RequestId": "20210811152539010225146063030****",
"TotalCount": 50
}
}
Error codes
This section displays only the error codes of the current API. For more error codes, see Common error codes.
Last updated: 2026.05.09 10:35:32
All rights reserved © Beijing Volcano Engine Technology Co., Ltd2024
