Updated on 2025-09-16 GMT+08:00

Listing ECSs

Function

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

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

N/A

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 of ECSs provisioned by rack in the same 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 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 of ECSs provisioned by rack in the same 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"
}

Error Codes

See Error Codes.