All Products
Search

This Product

    Server Load Balancer:ListServerGroups

    Document Center

    Server Load Balancer:ListServerGroups

    Last Updated:Mar 23, 2026

    Queries the server groups of a Gateway Load Balancer (GWLB) instance.

    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

    gwlb:ListServerGroups

    get

    ServerGroup

    acs:gwlb:{#regionId}:{#accountId}:servergroup/*

    ServerGroup

    acs:gwlb:{#regionId}:{#accountId}:servergroup/{#ServerGroupId}

    VPC

    acs:vpc:{#regionId}:{#accountId}:vpc/{#VpcId}

    None

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ServerGroupIds

    array

    No

    The server group IDs.

    You can specify at most 20 server group IDs in each call.

    string

    No

    The server group ID.

    sgp-atstuj3rtoptyui****

    ServerGroupNames

    array

    No

    The server group names.

    You can specify at most 20 server group names in each call.

    string

    No

    The server group name.

    testServerGroupName

    ServerGroupType

    string

    No

    The server group type. Valid values:

    • Instance: allows you to specify resources of the Ecs, Eni, or Eci type.

    • Ip: allows you to add servers by specifying IP addresses.

    Instance

    ResourceGroupId

    string

    No

    The ID of the resource group to which the instance belongs.

    rg-atstuj3rtop****

    Tag

    array<object>

    No

    The tag keys.

    You can specify at most 20 tags in each call.

    object

    No

    The tag.

    Key

    string

    No

    The tag key. The tag key cannot be an empty string. The tag key can be up to 128 characters in length, and cannot start with acs: or aliyun. The tag key cannot contain http:// or https://.

    testTagKey

    Value

    string

    No

    The tag value. The tag value can be up to 256 characters in length and cannot contain http:// or https://.

    testTagValue

    VpcId

    string

    No

    The VPC ID.

    vpc-bp15zckdt37pq72zv****

    NextToken

    string

    No

    The pagination token that is used in the next request to retrieve a new page of results. Valid values:

    • If NextToken is empty, no next page exists.

    • If a value of NextToken is returned, the value indicates the token that is used for the next query.

    FFmyTO70tTpLG6I3FmYAXGKPd****

    MaxResults

    integer

    No

    The number of entries per page.

    Valid values: 1 to 1000.

    Default value: 20.

    20

    Skip

    integer

    No

    The number of entries to be skipped in the call.

    1

    Response elements

    Element

    Type

    Description

    Example

    object

    The response parameters.

    MaxResults

    integer

    The number of entries per page.

    Valid values: 1 to 1000.

    20

    NextToken

    string

    A pagination token. It can be used in the next request to retrieve a new page of results. Valid values:

    • If NextToken is empty, no next page exists.

    • If a value of NextToken is returned, the value indicates the token that is used for the next query.

    FFmyTO70tTpLG6I3FmYAXGKPd****

    RequestId

    string

    The request ID.

    54B48E3D-DF70-471B-AA93-08E683A1B45

    ServerGroups

    array<object>

    The configurations of the server group.

    array<object>

    The server group.

    ConnectionDrainConfig

    object

    The configurations of connection draining.

    ConnectionDrainEnabled

    boolean

    Indicates whether connection draining is enabled. Valid values:

    • true

    • false

    false

    ConnectionDrainTimeout

    integer

    The timeout period of connection draining.

    Unit: seconds

    Valid values: 1 to 3600.

    300

    CreateTime

    string

    The time when the resource was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

    2024-08-05T18:24:07Z

    HealthCheckConfig

    object

    The configuration of health checks.

    HealthCheckConnectPort

    integer

    The backend server port that is used for health checks.

    Valid values: 1 to 65535.

    80

    HealthCheckConnectTimeout

    integer

    The maximum timeout period of a health check.

    Unit: seconds

    Valid values: 1 to 300.

    5

    HealthCheckDomain

    string

    The domain name that is used for health checks. Valid values:

    • $SERVER_IP: the internal IP address of a backend server.

    • domain: a domain name. The domain name must be 1 to 80 characters in length, and can contain letters, digits, hyphens (-), and periods (.).

    Note

    This parameter takes effect only if you set HealthCheckProtocol to HTTP.

    $SERVER_IP

    HealthCheckEnabled

    boolean

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

    • true

    • false

    true

    HealthCheckHttpCode

    array

    The HTTP status codes that the system returns for health checks.

    string

    The HTTP status code to return for health checks. Separate multiple HTTP status codes with commas (,). Valid values:

    • http_2xx

    • http_3xx

    • http_4xx

    • http_5xx

    Default value: http_2xx.

    Note

    This parameter takes effect only if you set HealthCheckProtocol to HTTP.

    http_2xx

    HealthCheckInterval

    integer

    The interval at which health checks are performed.

    Unit: seconds

    Valid values: 1 to 50.

    10

    HealthCheckPath

    string

    The URL that is used for health checks.

    The URL must be 1 to 80 characters in length, and can contain letters, digits, and the following special characters: - / . % ? # & The URL must start with a forward slash (/).

    Note

    This parameter takes effect only if you set HealthCheckProtocol to HTTP.

    /test/index.html

    HealthCheckProtocol

    string

    The protocol that is used for health checks. Valid values:

    • TCP: TCP health checks send TCP SYN packets to a backend server to check whether the port of the backend server is reachable.

    • HTTP: HTTP health checks simulate a process that uses a web browser to access resources by sending HEAD or GET requests to an instance. These requests are used to check whether the instance is healthy.

    TCP

    HealthyThreshold

    integer

    The number of times that an unhealthy backend server must consecutively pass health checks before it is declared healthy. In this case, the health status changes from fail to success.

    Valid values: 2 to 10.

    2

    UnhealthyThreshold

    integer

    The number of times that a healthy backend server must consecutively fail health checks before it is declared unhealthy. In this case, the health status changes from success to fail.

    Valid values: 2 to 10.

    2

    HealthCheckReq

    string

    HealthCheckExp

    string

    Protocol

    string

    The backend protocol. Valid values:

    • GENEVE.

    GENEVE

    RelatedLoadBalancerIds

    array

    The IDs of the GWLB instances that are associated with the server group.

    string

    The ID of the GWLB instance that is associated with the server group.

    gwlb-cp6prgqy40hols****

    ResourceGroupId

    string

    The resource group ID.

    rg-atstuj3rtop****

    Scheduler

    string

    The scheduling algorithm. Valid values:

    • 5TCH: indicates consistent hashing that is based on the following factors: source IP address, destination IP address, source port, protocol, and destination port. Requests that contain the same information based on the preceding factors are forwarded to the same backend server.

    • 3TCH: indicates consistent hashing that is based on the following factors: source IP address, destination IP address, and protocol. Requests that contain the same information based on the preceding factors are forwarded to the same backend server.

    • 2TCH: indicates consistent hashing that is based on the following factors: source IP address and destination IP address. Requests that contain the same information based on the preceding factors are forwarded to the same backend server.

    5TCH

    ServerCount

    integer

    The number of server groups.

    2

    ServerGroupId

    string

    The server group ID.

    sgp-atstuj3rtoptyui****

    ServerGroupName

    string

    The server group name.

    testServerGroupName

    ServerGroupStatus

    string

    The status of the server group. Valid values:

    • Creating

    • Available

    • Configuring

    Available

    ServerGroupType

    string

    The server group type. Valid values:

    • Instance: allows you to specify servers of the Ecs, Eni, or Eci type.

    • Ip: allows you to add servers of by specifying IP addresses.

    Instance

    ServerFailoverMode

    string

    Specifies how GWLB processes requests over existing connections when a backend server is not running as expected. Valid values:

    • NoRebalance: GWLB continues to forward requests over existing connections to the unhealthy backend server.

    • Rebalance: GWLB forwards requests over existing connections to the remaining healthy backend servers.

    NoRebalance

    Tags

    array<object>

    The tags.

    object

    The tag.

    Key

    string

    The tag key. The tag key cannot be an empty string. The tag key can be up to 128 characters in length, and cannot start with acs: or aliyun. The tag key cannot contain http:// or https://.

    testTagKey

    Value

    string

    The tag value. The tag value can be up to 256 characters in length and cannot contain http:// or https://.

    testTagValue

    VpcId

    string

    The VPC ID.

    vpc-bp15zckdt37pq72zv****

    TotalCount

    integer

    The total number of entries returned.

    1

    Examples

    Success response

    JSON format

    {
  "MaxResults": 20,
  "NextToken": "FFmyTO70tTpLG6I3FmYAXGKPd****",
  "RequestId": "54B48E3D-DF70-471B-AA93-08E683A1B45",
  "ServerGroups": [
    {
      "ConnectionDrainConfig": {
        "ConnectionDrainEnabled": false,
        "ConnectionDrainTimeout": 300
      },
      "CreateTime": "2024-08-05T18:24:07Z",
      "HealthCheckConfig": {
        "HealthCheckConnectPort": 80,
        "HealthCheckConnectTimeout": 5,
        "HealthCheckDomain": "$SERVER_IP",
        "HealthCheckEnabled": true,
        "HealthCheckHttpCode": [
          "http_2xx"
        ],
        "HealthCheckInterval": 10,
        "HealthCheckPath": "/test/index.html",
        "HealthCheckProtocol": "TCP",
        "HealthyThreshold": 2,
        "UnhealthyThreshold": 2,
        "HealthCheckReq": "",
        "HealthCheckExp": ""
      },
      "Protocol": "GENEVE",
      "RelatedLoadBalancerIds": [
        "gwlb-cp6prgqy40hols****"
      ],
      "ResourceGroupId": "rg-atstuj3rtop****",
      "Scheduler": "5TCH",
      "ServerCount": 2,
      "ServerGroupId": "sgp-atstuj3rtoptyui****",
      "ServerGroupName": "testServerGroupName",
      "ServerGroupStatus": "Available",
      "ServerGroupType": "Instance",
      "ServerFailoverMode": "NoRebalance",
      "Tags": [
        {
          "Key": "testTagKey",
          "Value": "testTagValue"
        }
      ],
      "VpcId": "vpc-bp15zckdt37pq72zv****"
    }
  ],
  "TotalCount": 1
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.