Updated on 2026-08-14 GMT+08:00

Listing ECS Groups

Function

This API is used to list ECS groups.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned.

If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.
If you are using identity policy-based authorization, the permissions listed below are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
ecs:cloudServers:listServerGroups	list	-	-	ecs:cloudServers:list	-

URI

GET /v1/{project_id}/cloudservers/os-server-groups

Table 1 describes the parameters in the URI.

**Table 1** Path parameters
Parameter	Mandatory	Description
project_id	Yes	Definition Specifies the project ID. For details about how to obtain the ID, see Obtaining a Project ID. Constraints N/A Range N/A Default Value N/A

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
limit	No	Integer	Definition Specifies the maximum number of server groups that can be returned. Constraints Maximum: 1000 Range 1–1000 Default Value N/A
marker	No	String	Definition Specifies the pagination marker. The ID of the last server group on each page is used as the pagination marker. The query will start from the next server group. Constraints Parameters marker and limit must be used together. Range N/A Default Value N/A

Request

None

Response

Table 3 describes the response parameters.

**Table 3** Response parameters
Parameter	Type	Description
server_groups	Array of objects	Definition Specifies ECS groups. For details, see Table 4. Range N/A
page_info	Object	Definition If the pagination function is enabled, the UUID of the last ECS group on the current page is returned. For details, see Table 5. Range N/A

**Table 4** **server_groups** parameter information
Parameter	Type	Description
id	String	Definition Specifies the ECS group UUID. Range N/A
name	String	Definition Specifies the ECS group name. Range N/A
members	Array of strings	Definition Specifies the ECSs contained in an ECS group. Range N/A
metadata	Object	Definition Specifies the ECS group metadata. Range N/A
policies	Array of strings	Definition Specifies the policies associated with the ECS group. Range anti-affinity: ECSs in this group must be deployed on different hosts.

**Table 5** **page_info** field description
Parameter	Type	Description
next_marker	String	Definition Specifies an ECS group UUID. Range N/A

Example Request

List ECS groups.

GET https://{endpoint}/v1/{project_id}/cloudservers/os-server-groups

Example Response

{
   "server_groups": [
      {
         "members": [],
         "metadata": {},
         "id": "318b44a7-f7a6-4c0b-8107-e8bd618b28dd",
         "policies": [
                     "anti-affinity"
                     ],
         "name": "SvrGrp-b9d6"
  },
  {
         "members": [],
         "metadata": {},
         "id": "b8f4cfc4-9a59-498c-9b52-643ee6515cd0",
         "policies": [
                     "anti-affinity"
                     ],
         "name": "SvrGrp-10a1"
  }
 ]
}

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Codes.

Parent topic: ECS Group Management