Listing ECSs

Function

This API is used to list ECSs and obtain their details based on the search criteria.

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:listServersDetails	list	-	g:EnterpriseProjectId	ecs:cloudServers:list	-

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

ecs:cloudServers:listServersDetails

list

g:EnterpriseProjectId

ecs:cloudServers:list

URI

GET /v1.1/{project_id}/cloudservers/detail

Table 1 describes the parameters in the URI.

**Table 1** Path parameters
Parameter	Mandatory	Description
project_id	Yes	Specifies the project ID. For details about how to obtain the ID, see Obtaining a Project ID.

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
marker	No	String	Definition Specifies the ID of the last server on each page as the paging marker. Constraints Parameters marker and limit must be used together. If the number of records returned on the last page is less than the value of limit, the query ends. Range N/A Default Value N/A
flavor_name	No	String	Definition Specifies the name of the ECS flavor. For details about available flavors, see A Summary List of x86 ECS Specifications. Constraints N/A Range N/A Default Value N/A
name	No	String	Definition Specifies the cloud name. Fuzzy match is supported. Constraints Periods (.) are supported to match any single characters except \n and \r. A period is equal to [^\n\r]. Range N/A Default Value N/A
status	No	String	Definition Specifies the ECS status. Constraints N/A Range ACTIVE, BUILD, ERROR, HARD_REBOOT, MIGRATING, REBOOT, REBUILD, RESIZE, REVERT_RESIZE, SHUTOFF, and VERIFY_RESIZE For details about the ECS status, see ECS Statuses. NOTE: When an ECS is in an intermediate state, the statuses that can be obtained are as follows: ACTIVE: ACTIVE, REBOOT, HARD_REBOOT, REBUILD, or MIGRATING SHUTOFF: SHUTOFF, RESIZE, or REBUILD ERROR: ERROR or REBUILD VERIFY_RESIZE: VERIFY_RESIZE or REVERT_RESIZE Default Value N/A
limit	No	Integer	Definition Specifies the maximum number of ECSs on one page. Constraints Each page contains 10 ECSs by default and a maximum of 100 ECSs. Range N/A Default Value N/A
tags	No	String	Definition Queries ECSs whose tags contain the specified value. Constraints N/A Range N/A Default Value N/A
not-tags	No	String	Definition Queries ECSs whose tags do not contain the specified value. For example, if the queried ECS list should not contain BMSs, set this parameter as follows: not-tags=__type_baremetal Constraints N/A Range N/A Default Value N/A
project_id	No	String	Definition Specifies the project ID. Constraints N/A Range N/A Default Value N/A
availability_zone_eq	No	String	Definition Specifies the AZ where the ECS resides. The matching rule is exact match. Constraints N/A Range N/A Default Value N/A
id	No	String	Definition Specifies the ECS ID in the UUID format, which is exactly matched. For example: id={id1}&id={id2}. Constraints N/A Range N/A Default Value N/A
in_recycle_bin	No	Boolean	Definition Specifies whether the ECS is in the recycle bin. Constraints N/A Range N/A Default Value N/A
spod_id	No	String	Definition Specifies the ID of the batch for provisioning bare metal ECSs by rack in the shared resource pool. Constraints N/A Range N/A Default Value N/A
metadata	No	Object	Definition Specifies the ECS metadata. NOTE: Metadata includes system default fields and the fields set by users. Constraints N/A Range N/A Default Value N/A
metadata-key	No	String	Definition Filters ECSs whose key of the metadata field contains a specified value. Constraints N/A Range N/A Default Value N/A
charging_mode	No	String	Definition Specifies the ECS billing mode. Constraints N/A Range N/A Default Value N/A
key_name	No	String	Definition Specifies the key pair that is used to authenticate an ECS. Constraints N/A Range N/A Default Value N/A
launched_since	No	String	Definition Filters ECSs that are started after the time specified by launched_since. The parameter is in ISO 8601 time format, for example, 2013-06-09T06:42:18Z. Constraints N/A Range N/A Default Value N/A
expect-fields	No	String	Definition Controls the query output. It controls whether to query based on the default field. Constraints N/A Range launched_at: the time when an ECS was started key_name: the key pair that is used to authenticate an ECS locked: whether an ECS is locked root_device_name: the device name of the ECS system disk tenancy: creating ECSs on a DeH or in a shared pool dedicated_host_id: DeH ID enterprise_project_id: querying the ECSs that are associated with an enterprise project tags: list of ECS tags metadata: ECS metadata addresses: network addresses of an ECS security_groups: information about the security group associated with the ECS volumes_attached: information about the disks attached to the ECS image: ECS image power_state: ECS power status cpu_options: custom CPU options market_info: ECS billing information, including the billing type and expiration time Default Value N/A

Request

None

Response

Table 3 describes the response parameters.

**Table 3** Response parameters
Parameter	Type	Description
servers	Array of objects	Definition Queries details about ECSs. For details, see Table 5. Range N/A
servers_links	Array of objects	Definition Specifies the link of the next page in pagination query. For details, see Table 4. Range N/A
request_id	String	Definition Specifies the request ID. Range N/A

**Table 4** **servers_links** field description
Parameter	Type	Description
href	String	Definition Specifies the resource link. Range N/A
rel	String	Definition Provides the corresponding shortcut link. Range N/A

**Table 5** **servers** field description
Parameter	Type	Description
tenant_id	String	Definition Specifies the ID of the tenant that the ECS belongs to, in UUID format. It is the same as the project ID. Range N/A
vm_state	String	Definition Specifies a stable ECS state after an operation is complete. Range N/A
flavor	Object	Definition Specifies ECS flavor information. For details, see Table 2. Range N/A
availability_zone	String	Definition Specifies the name of the AZ where the ECS is located. Range N/A
user_id	String	Definition Specifies the ID of the user for creating an ECS, in UUID format. Range N/A
created	String	Definition Specifies the time when the ECS was created. The time is in the format of "2019-05-22T03:19:19Z". Range N/A
name	String	Definition Specifies the ECS name. Range N/A
task_state	String	Definition Specifies the task status of the ECS. Range N/A
id	String	Definition Specifies the ECS ID in UUID format. Range N/A
status	String	Definition Specifies the ECS status. Range N/A
market_info	Object	Definition Specifies the ECS billing information. For details, see Table 6. Range N/A
availability_zone	String	Definition Specifies the AZ where the ECS is located. Range N/A
power_state	Integer	Definition Specifies the ECS power status. Range 0: NOSTATE 1: RUNNING 2: SHUTDOWN
in_recycle_bin	Boolean	Definition Specifies whether the ECS is in the recycle bin. Range N/A
spod_id	String	Definition Specifies the ID of the batch for provisioning bare metal ECSs by rack in the shared resource pool. Range N/A
created	String	Definition Specifies the time when the ECS was created. The time is in the format of "2020-05-22T07:48:53Z". Range N/A
updated	String	Definition Specifies the time when the ECS was updated last time. The time is in the format of "2020-05-22T07:48:53Z". Range N/A
launched_at	String	Definition Specifies the time when the ECS was started. The time is in the format of "2020-05-22T07:48:53.000000". Range N/A
description	String	Definition Specifies the description of the ECS. Range N/A
key_name	String	Definition Specifies the key pair that is used to authenticate an ECS. Range N/A
locked	Boolean	Definition Specifies whether an ECS is locked. Range true: The ECS is locked. false: The ECS is not locked.
root_device_name	String	Definition Specifies the device name of the ECS system disk. For example, if the system disk device type is VBD, the device name is /dev/vda. Range N/A
tenancy	String	Definition Specifies whether to create ECSs on a DeH or in a shared pool. By default, ECSs are created in a shared pool. Range shared: shared pool dedicated: DeH
dedicated_host_id	String	Definition Specifies the DeH ID. This parameter is valid only when tenancy is dedicated. If this parameter is not specified, the system automatically allocates a DeH for the tenant to deploy ECSs. Range N/A
enterprise_project_id	String	Definition Queries the ECSs that are associated with an enterprise project. To obtain the ECSs associated with all enterprise projects of the user, set all_granted_eps. Range N/A
metadata	Object	Definition Specifies the ECS metadata. Range N/A
tags	Array of strings	Definition Specifies the list of ECS tags. Range N/A
addresses	Object	Definition Specifies the network addresses of an ECS. The structure is Map<String, Object>. Range The key indicates the network name, for example, demo_net. The value indicates the network attribute specified in Table 7.
security_groups	Array of objects	Definition Specifies the security group associated with the ECS. For details, see Table 3. Range N/A
volumes_attached	Array of objects	Definition Specifies information about the disks attached to the ECS. For details, see Table 10. Range N/A
image	Object	Definition Specifies the ECS image. For details, see Table 7. Range N/A
fault	Object	Definition Specifies the ECS failure cause. Range If the ECS status is normal, NULL is returned. If the ECS status is abnormal, a failure message or details are returned. For details, see Table 9.
cpu_options	Object	Definition Specifies the CPU options. For details, see Table 11. Range N/A

**Table 6** **market_info** field description
Parameter	Type	Description
charge_mode	String	Definition Specifies the ECS billing mode. Range spot: spot pricing prepaid: yearly/monthly postpaid: pay-per-use
prepaid_info	Object	Definition Specifies the information about the yearly/monthly ECS. For details, see Table 8. Range N/A

**Table 7** **addresses** field description
Parameter	Type	Description
version	Integer	Definition Specifies the IP address version. Range 4: indicates IPv4. 6: indicates IPv6.
addr	String	Definition Specifies the IP address. Range N/A
primary	Boolean	Definition Specifies whether the network interface is a primary network interface. Range true: It is a primary network interface. false: It is a supplementary network interface.
OS-EXT-IPS:type	String	Definition Specifies the IP address type. Range fixed: indicates the private IP address. floating: indicates the floating IP address.
OS-EXT-IPS-MAC:mac_addr	String	Definition Specifies the MAC address. Range N/A
OS-EXT-IPS:port_id	String	Definition Specifies the port ID corresponding to the IP address. Range N/A

**Table 8** **prepaid_info** field description
Parameter	Type	Description
expired_time	String	Definition Specifies the expiration time of the yearly/monthly ECS. The time is in the format of "2020-05-22T07:48:53Z". Range N/A

**Table 9** **fault** field description
Parameter	Type	Description
code	Integer	Definition Specifies an error code. The format is int32. Range N/A
created	String	Definition Specifies the time when an exception occurred. The time is in ISO 8601 format. Range N/A
message	String	Definition Describes an error. Range N/A
details	String	Definition Specifies details about an error. Range N/A

**Table 10** **volumes_attached** field description
Parameter	Type	Description
id	String	Definition Specifies the disk ID in UUID format. Range N/A
delete_on_termination	Boolean	Definition Specifies whether to delete the attached disks when deleting the ECS. This parameter is supported in microversion 2.3 and later. Range true: The attached disks are deleted along with the ECS. false: The attached disks are not deleted along with the ECS.
bootIndex	String	Definition Specifies the EVS disk boot sequence. Range 0 indicates the system disk. Non-0 indicates a data disk.
device	String	Definition Specifies the drive letter of the EVS disk, which is the device name of the EVS disk. Range N/A
size	Integer	Definition Specifies the disk size in GiB. Range N/A

**Table 11** **cpu_options** field description
Parameter	Type	Description
hw:cpu_threads	Integer	Definition Specifies whether to enable CPU hyper-threading. This parameter can be set to 1 (disabling hyper-threading) only when all of the following conditions are met: The ECS is being created or resized. The extra_specs parameter of the target flavor contains: hw:cpu_policy, whose value is set to dedicated hw:cpu_threads, whose value is set to 2 Range 1: Disable hyper-threading. 2: Enable hyper-threading.

Example Request

GET https://{endpoint}/v1.1/{project_id}/cloudservers/detail

Example Response

{
    "servers": [
        {
            "tenant_id": "edcb94a885a84ed3a3fdf8ea4d2741da",
            "vm_state": "active",
            "flavor": {
                "disk": 0,
                "name": "s2.medium.2",
                "id": "s2.medium.2",
                "vcpus": 1,
                "ram": 2048,
                "gpus":[],
                "asic_accelerators":[]
            },
            "availability_zone": "az1-dc1",
            "user_id": "bb7f23e27e7e46f3aaceb5f53a158bdc",
            "created": "2023-03-18T09:02:36Z",
            "name": "ecs-5e70",
            "task_state": null,
            "in_recycle_bin": false,
            "id": "b37fd80e-ac67-4d02-b9f1-9891c9c0fabf",
            "updated": "2023-03-18T09:08:54Z",
            "spod_id": null,
            "status": "ACTIVE"
        },
        {
            "tenant_id": "edcb94a885a84ed3a3fdf8ea4d2741da",
            "vm_state": "active",
            "flavor": {
                "disk": 0,
                "name": "s3.small.1",
                "id": "s3.small.1",
                "vcpus": 1,
                "ram": 1024,
                "gpus":[],
                "asic_accelerators":[]
            },
            "availability_zone": "az1-dc1",
            "user_id": "bb7f23e27e7e46f3aaceb5f53a158bdc",
            "created": "2023-03-18T04:29:44Z",
            "name": "ecs-f680",
            "task_state": null,
            "in_recycle_bin": false,
            "id": "8380dcc9-0eac-4407-9f9e-df8c9eddeacd",
            "updated": "2023-03-18T04:40:25Z",
            "spod_id": null,
            "status": "ACTIVE"
        }
    ],
    "servers_links": [
        {
            "rel": "next",
            "href": ""
        }
    ],
    "request_id": "2da856f5-95e6-437f-9f8b-ae7dc00a9ace"
}