Help Center/Elastic Cloud Server/API Reference/APIs/Lifecycle Management/Listing ECSs
Updated on 2026-03-19 GMT+08:00
View PDF
Share

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

-

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

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

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 ECS name. Fuzzy match is supported.

Constraints

Special characters are supported. For example, periods (.) 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 ECS statuses, see ECS Statuses.

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. The matching rule is exact match.

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 metadata keys contain the 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 name of the key pair used by 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 chooses whether to include additional fields beyond the defaults.

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

  • building: The ECS has been created but is not running yet.
  • active: The ECS is running properly.
  • stopped: The ECS has been properly stopped.
  • resized: The ECS has been resized (specifications have been modified).
  • error: The ECS is abnormal.
  • deleted: The ECS has been deleted.
  • shelved: The ECS booting from an image is shelved.
  • shelved_offloaded: The ECS booting from a volume is shelved.

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

  • scheduling: The system is scheduling resources when the ECS is being created.
  • block_device_mapping: Disks are being prepared for the ECS that is being created.
  • networking: Networking resources are being prepared for the ECS that is being created.
  • spawning: The ECS is being created internally.
  • rebooting: The ECS is being restarted.
  • reboot_pending: The ECS is pending a restart.
  • reboot_started: The ECS is being restarted internally.
  • rebooting_hard: The ECS is being forcibly restarted.
  • reboot_pending_hard: The ECS is pending a force restart.
  • reboot_started_hard: The ECS is being forcibly restarted internally.
  • rebuilding: The ECS is being rebuilt.
  • rebuild_block_device_mapping: Disks are being prepared for the ECS that is being rebuilt.
  • rebuild_spawning: The ECS is being rebuilt internally.
  • migrating: The ECS is undergoing live migration.
  • resize_prep: The ECS is preparing for being resized.
  • resize_migrating: The ECS is undergoing migration during the resize phase.
  • resize_migrated: The ECS has finished migration during the resize phase.
  • resize_finish: The ECS is finishing the resize operation during the resize phase.
  • resize_reverting: The ECS is rolling back to its previous size during the resize phase.
  • powering-off: The ECS is being stopped.
  • powering-on: The ECS is being started.
  • deleting: The ECS is being deleted.
  • shelving: The ECS booting from an image is being shelved.
  • shelving_offloading: The ECS booting from a volume is being shelved.
  • shelving_image_pending_upload: A shelving image is pending upload.
  • shelving_image_uploading: A shelving image is being uploaded.
  • unshelving: The ECS is being unshelved.

id

String

Definition

Specifies the ECS ID in UUID format.

Range

N/A

status

String

Definition

Specifies the ECS status.

Range

ACTIVE, BUILD, ERROR, HARD_REBOOT, MIGRATING, REBOOT, REBUILD, RESIZE, REVERT_RESIZE, SHUTOFF, and VERIFY_RESIZE

For details about ECS statuses, see ECS Statuses.

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"
}

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Codes.