tencent cloud

APIs

DocumentationAPIsCloud Load BalancerListener APIsCreateListener

CreateListener

Download
Focus Mode
Font Size
Last updated: 2026-06-17 17:27:05

1. API Description

Domain name for API request: clb.intl.tencentcloudapi.com.

This API is used to create a listener for a CLB instance.
This is an asynchronous API. After it returns the result successfully, you can call the DescribeTaskStatus API with the returned RequestId as an input parameter to query whether the task is successful.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: CreateListener.
Version Yes String Common Params. The value used for this API: 2018-03-17.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
LoadBalancerId Yes String

ID of the Cloud Load Balancer (CLB) instance. You can call the DescribeLoadBalancers API to obtain the ID.
Ports.N Yes Array of Integer

Which ports to create listeners on, each port maps to a new listener.
Port range: 1–65535
Protocol Yes String

Listener protocol. Valid values: TCP, UDP, HTTP, HTTPS, TCP_SSL, and QUIC.
ListenerNames.N No Array of String

List of listener names to be created. Names correspond sequentially to Ports. If naming is not immediately necessary, this parameter need not be provided. Naming rule: 1-80 characters including English letters, Chinese characters, digits, connecting line "-", underscore "_" and other common characters (Unicode supplementary characters such as emoji and rare Chinese characters are forbidden).
HealthCheck No HealthCheck

Health check parameters. This parameter is applicable only to TCP/UDP/TCP_SSL/QUIC listeners.
Certificate No CertificateInput

Certificate-related information. The limits are as follows:

  • This parameter is applicable only to TCP_SSL listeners and HTTPS listeners with SNI feature disabled.
  • When creating a TCP_SSL listener or an HTTPS listener with SNI feature disabled, a minimum of this parameter or MultiCertInfo must be specified, but they cannot be specified at the same time.
    		•
    SessionExpireTime No Integer

    Session persistence duration, in seconds. Value range: 30–3600. Default value: 0, indicating that session persistence is not enabled by default. This parameter applies only to TCP and UDP listeners.
    Scheduler No String

    Listener forwarding mode. Available values: WRR (weighted round-robin), LEAST_CONN (least connections).
    Default WRR. This parameter is applicable only to TCP/UDP/TCP_SSL/QUIC listeners.
    SniSwitch No Integer

    Whether to enable SNI feature. This parameter applies only to HTTPS listeners. 0: not enabled, 1: enable.
    TargetType No String

    Backend target type. NODE indicates binding to a general node. TARGETGROUP indicates binding to a target group. This parameter is applicable only to TCP/UDP listeners. For layer-7 (HTTP/HTTPS) listeners, configure it in forwarding rules.
    SessionType No String

    Session persistence type. Leaving it blank or passing NORMAL means the default session persistence type. QUIC_CID refers to maintaining the session based on QUIC Connection ID. QUIC_CID supports only UDP Protocol. This parameter is applicable only to TCP/UDP listeners. Layer-7 (HTTP/HTTPS) listeners should set this in forwarding rules. (If QUIC_CID is selected, Protocol must be UDP, Scheduler must be WRR, and it supports only ipv4 concurrently).
    KeepaliveEnable No Integer

    Whether to enable long connections. This parameter is applicable only to HTTP/HTTPS listeners. 0: off by default; 1: enable.
    If the backend service has a connection limit, enable with caution. This feature is currently in internal testing. If you need to use it, submit a beta application.
    EndPort No Integer

    End port. This parameter is required for creating a listener with a port range. In this case, the input parameter Ports allows only one value to indicate the start port. To experience the port range feature, submit a ticket for application.
    DeregisterTargetRst No Boolean

    Rescheduling feature, which provides a switch for scaling out the backend service. If the switch is toggled on, rescheduling is triggered when the backend service is unbound. This parameter is applicable only to TCP/UDP listeners.
    MultiCertInfo No MultiCertInfo

    Certificate information. Multiple server certificates with different algorithm types can be imported at the same time. Parameter constraints are as follows:

  • This parameter is applicable only to TCP_SSL listeners and HTTPS listeners with SNI feature disabled.
  • When creating a TCP_SSL listener or an HTTPS listener with SNI feature disabled, a minimum of this parameter or Certificate must be specified, but they cannot be specified at the same time.
    		•
    MaxConn No Integer

    Maximum number of connections to a listener. Currently, this parameter applies only to TCP, UDP, TCP_SSL, and QUIC listeners of LCU-supported instances. If this parameter is not specified or the value is set to -1, the maximum number of connections is not limited. This parameter is not supported for classic network-based instances.
    MaxCps No Integer

    Maximum number of new connections to a listener. Currently, this parameter applies only to TCP, UDP, TCP_SSL, and QUIC listeners of LCU-supported instances. If this parameter is not specified or the value is set to -1, the maximum number of new connections is not limited. This parameter is not supported for classic network-based instances.
    IdleConnectTimeout No Integer

    Idle connection timeout, in seconds. This parameter applies only to TCP/UDP listeners. Default value: 900 for TCP listeners and 300 for UDP listeners. Value range: 10–900 for shared instances and dedicated instances and 10–1980 for LCU-supported instances. To set a value exceeding the permissible range, submit a ticket for application.

    Permissible range: [10, 1980]

    Measurement unit: seconds

    Default value: 900

    Default value: 900 for TCP listeners and 300 for UDP listeners. Value range: 10–900 for shared instances and dedicated instances and 10–1980 for LCU-supported instances.
    ProxyProtocol No Boolean

    Whether TCP_SSL and QUIC support PP
    SnatEnable No Boolean

    Whether SNAT (source IP replacement) is enabled, True (enabled), False (disabled). Disabled by default. Note: When SnatEnable is enabled, the client source IP will be replaced. At this point, the Pass through client source IP option is disabled, and vice versa.
    FullEndPorts.N No Array of Integer

    End port of a listener with a port range. Range of the port: 2–65535.
    H2cSwitch No Boolean

    Enable the h2c switch for the private network HTTP listener.
    True (enabled), False (disabled). Disabled by default.
    Once enabled, the listener only supports creating layer-7 rules with GRPC or GRPCS as the backend forwarding type. When creating rules, explicitly input GRPC or GRPCS in Rules.N.ForwardType.
    SslCloseSwitch No Boolean

    Control whether to remove the SSL encryption layer for TCP_SSL listeners. Once enabled, the listener will run as a normal TCP protocol. Available values:

    • True: Disable SSL (protocol downgraded to plain text TCP).
    • False (default): Keep SSL enabled.
    DataCompressMode No String

    Data compression mode. Valid values: transparent (passthrough mode) and compatibility (compatibility mode).
    RescheduleTargetZeroWeight No Boolean

    Rescheduling feature, which provides a switch for changing the weight to 0. If the switch is toggled on, rescheduling is triggered when the weight of a real server is changed to 0. This parameter is applicable only to TCP/UDP listeners.
    RescheduleUnhealthy No Boolean

    Rescheduling feature, which provides a switch for detecting health check exceptions. If the switch is toggled on, rescheduling is triggered when the real server health check fails. This parameter is applicable only to TCP/UDP listeners.
    RescheduleExpandTarget No Boolean

    Rescheduling feature, which provides a switch for scaling out real servers. If the switch is toggled on, rescheduling is triggered when the number of real servers increases or decreases. This parameter is applicable only to TCP/UDP listeners.
    RescheduleStartTime No Integer

    Rescheduling trigger start time. Value range: 0–3600. Unit: s. This parameter is applicable only to TCP/UDP listeners.
    RescheduleInterval No Integer

    Rescheduling trigger duration. Value range: 0–3600. Unit: s. This parameter is applicable only to TCP/UDP listeners.

    3. Output Parameters

    Parameter Name Type Description
    ListenerIds Array of String

    Array of the unique IDs of created listeners.
    RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

    4. Example

    Example1 Creating an HTTPS Listener and Binding a New Certificate

    This example shows you how to create an HTTPS listener and bind a new certificate.

    Input Example

    POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateListener
<Common request parameters>

{
    "Protocol": "HTTPS",
    "Ports": [
        7573
    ],
    "Certificate": {
        "SSLMode": "UNIDIRECTIONAL",
        "CertContent": "-----BEGINCERTIFICATE-----\\nxxxxxxxxxxxxxxxxxxxxxxx\\n-----ENDCERTIFICATE-----",
        "CertName": "my-cert",
        "CertKey": "-----BEGINRSAPRIVATEKEY-----\\nxxxxxxxxxxxxxxxxxxxxxxxx\\n-----ENDRSAPRIVATEKEY-----"
    },
    "LoadBalancerId": "lb-cuxw2rm0"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-bzfmg9m6"
        ],
        "RequestId": "6082314c-030c-429d-9eae-2dc6b159b5b9"
    }
}

    Example2 Creating an HTTPS Listener and Binding an Existing Certificate

    This example shows you how to create an HTTPS listener and bind an existing certificate.

    Input Example

    POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateListener
<Common request parameters>

{
    "Protocol": "HTTPS",
    "Ports": [
        7572
    ],
    "Certificate": {
        "SSLMode": "UNIDIRECTIONAL",
        "CertId": "MsJyaXVm"
    },
    "LoadBalancerId": "lb-cuxw2rm0"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-4fbxq45k"
        ],
        "RequestId": "db8ae69f-ebda-402b-8d02-ead459aa6ff9"
    }
}

    Example3 Creating a TCP Listener and Configuring the Health Check Settings

    This example shows you how to create a TCP listener and configure the health check settings.

    Input Example

    POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateListener
<Common request parameters>

{
    "HealthCheck": {
        "UnHealthNum": 4,
        "HealthNum": 4,
        "IntervalTime": 7,
        "TimeOut": 5,
        "HealthSwitch": 1
    },
    "Protocol": "TCP",
    "Ports": [
        7571
    ],
    "LoadBalancerId": "lb-cuxw2rm0"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-lbbxvq26"
        ],
        "RequestId": "fff13c83-dcb5-481a-ba7c-30e92c276c19"
    }
}

    Example4 Creating a UDP Listener with the Default Ping Health Check

    This example shows you how to create a UDP listener with the default Ping health check.

    Input Example

    POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateListener
<Common request parameters>

{
    "HealthCheck": {
        "HealthSwitch": 1
    },
    "Protocol": "UDP",
    "ListenerNames": [
        "lis_test"
    ],
    "Ports": [
        432
    ],
    "LoadBalancerId": "lb-6wlxe9rj"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-aev333n1"
        ],
        "RequestId": "3b81f03e-6088-448d-abaf-8a487d4f985a"
    }
}

    Example5 Creating Two TCP Listeners (Respectively Named lis0 and lis1) to Respectively Listen on Ports 7569 and 7570

    This example shows you how to create two TCP listeners (respectively named lis0 and lis1) to respectively listen on ports 7569 and 7570.

    Input Example

    POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateListener
<Common request parameters>

{
    "ListenerNames": [
        "lis1",
        "lis0"
    ],
    "Protocol": "TCP",
    "Ports": [
        7570,
        7569
    ],
    "LoadBalancerId": "lb-cuxw2rm0"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-d1ubsydq",
            "lbl-4udz130k"
        ],
        "RequestId": "8f272cef-14ff-458c-b67e-1bd21bd2942b"
    }
}

    Example6 Create a listener and enable rescheduling

    Input Example

    POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateListener
<Common request parameters>

{
    "LoadBalancerId": "lb-fd9kpk4s",
    "Ports": [
        5689
    ],
    "Protocol": "tcp",
    "RescheduleTargetZeroWeight": true,
    "RescheduleUnhealthy": true,
    "RescheduleExpandTarget": true,
    "RescheduleStartTime": 25,
    "RescheduleInterval": 50
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-1sf4yxie"
        ],
        "RequestId": "6aa274e5-ff78-4e9e-b13c-30a9e21b107e"
    }
}

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    FailedOperation Operation failed.
    FailedOperation.ResourceInOperating The specified resource is currently being operated. Please try again later.
    InternalError Internal error.
    InvalidParameter Parameter error.
    InvalidParameter.FormatError Incorrect parameter format.
    InvalidParameter.PortCheckFailed Listener port check due to port conflicts or other reasons.
    InvalidParameterValue Parameter value error.
    InvalidParameterValue.Length Invalid parameter length.
    LimitExceeded The quota limit is exceeded.
    MissingParameter Parameters are missing.
    ResourceInsufficient Insufficient resources.
    UnauthorizedOperation Unauthorized operation.
    Previous Topic: DeleteLoadBalancerNext Topic: CreateRule

    Help and Support

    Was this page helpful?

    Help us improve! Rate your documentation experience in 5 mins.

    Feedback