Querying the Instance List

Function

This API is used to query the instance list.

Calling Method

For details, see Calling APIs.

URI

GET /v1/{project_id}/instances

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. Constraints N/A Range Project ID of the account. Default Value N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
limit	No	String	Definition Number of records on each page for pagination query. Constraints N/A Range Value range: 10 to 1000. If this parameter is not set or is set to a value less than 10, the default value 10 is used. If the value is greater than 1,000, the default value 1000 is used. Default Value 1000
marker	No	String	Definition Query address of the next page. Constraints N/A Range N/A Default Value N/A
instance_state	No	String	Definition Instance status. Constraints N/A Range pending: The instance is being started (resources are being allocated or the OS is being started). running: The instance is running properly (can be connected through SSH or RDP). stopping: The instance is being stopped (transiting to the stopped or hibernated state). stopped: The instance is completely stopped (storage volumes are retained). reinstalling: The OS is being reinstalled. shutting-down: The instance is being terminated (being deleted). terminated: The instance has been terminated (all resources are deleted and cannot be restored). failed: The instance is in the failed state. You can try to reinstall the OS. Other operations cannot be retried, and related resources will be cleared. Default Value N/A
instance_id	No	String	Definition Instance ID. The value can be an array consisting of multiple instance IDs. Constraints N/A Range A maximum of 100 IDs separated by commas (,) are supported, for example, uuid1,uuid2,uuid3. Default Value N/A
server_id	No	String	Definition Server IDs. The value can be an array consisting of multiple server IDs. Constraints This parameter is mutually exclusive with instance_id_set. Range A maximum of 100 IDs separated by commas (,) are supported, for example, uuid1,uuid2,uuid3. Default Value N/A

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition Requests for calling an API can be authenticated using a token. If token-based authentication is used, this parameter is mandatory and must be set to a user token. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
instances	Array of QueryInstanceResponseBody objects	Instance list.
page_info	PageInfo object	Definition Pagination information. Constraints N/A
count	Integer	Total number of instances.

**Table 5** QueryInstanceResponseBody
Parameter	Type	Description
id	String	Definition Instance ID. Constraints N/A Range N/A Default Value N/A
name	String	Definition Instance name. Constraints N/A Range N/A Default Value N/A
vpc_id	String	Definition ID of the VPC which the network interface to be created belongs to. You can query the ID using the VPC API: https://support.huaweicloud.com/intl/en-us/api-vpc/vpc_api01_0003.html. Constraints N/A Range VPC ID Default Value N/A
network_interfaces	Array of NetworkInterface objects	Definition Network interface information of the specified iMetal server. Constraints A maximum of two network interfaces can be attached to an iMetal server, and the first one serves as the primary network interface. If multiple network interfaces are specified, ensure that all network interfaces belong to the same VPC.
tags	Array of Tag objects	Definition Tags. Constraints N/A
image	Image object	Definition Server image information. Constraints N/A
description	String	Definition Description of the iMetal Instance. Constraints N/A Range N/A Default Value Empty string
state	String	Definition The instance status. Constraints N/A Range pending: The instance is being started (resources are being allocated or the OS is being started). running: The instance is running properly (can be connected through SSH or RDP). stopped: The instance is completely stopped (storage volumes are retained). shutting-down: The instance is being terminated (being deleted). terminated: The instance has been terminated (all resources are deleted and cannot be restored). error: The instance is abnormal (resources are not completely deleted). Default Value N/A
operation_state	String
metadata	Map<String,String>	Definition Metadata for creating an iMetal instance. You can use metadata to customize key-value pairs. If the metadata contains sensitive data, take appropriate measures to protect the sensitive data, for example, controlling access permissions and encrypting the data. Constraints N/A Range A maximum of 10 key-value pairs can be injected. A metadata key consists of 1 to 255 characters and can only contain uppercase letters, lowercase letters, spaces, digits, hyphens (-), underscores (_), colons (:), and periods (.). A metadata value consists of a maximum of 255 characters. Default Value N/A
user_data	String	Definition User data to be injected during instance creation. Constraints N/A Range The content of user_data must be encoded with Base64. Maximum size (before encoding): 32 KB Default Value N/A
server_id	String	Definition Server ID. Constraints N/A Range The value is in UUID format. Default Value N/A
created_at	String	Definition Creation time. Constraints N/A Range The value is in RFC 3339 format, for example, 2025-04-22T12:03:18.50083+08:00. Default Value N/A
updated_at	String	Definition Update time. Constraints N/A Range The value is in RFC 3339 format, for example, 2025-04-22T12:03:18.50083+08:00. Default Value N/A
launched_at	String	Definition Start time. Constraints N/A Range The value is in RFC 3339 format, for example, 2025-04-22T12:03:18.50083+08:00. Default Value N/A
error	ErrorStatus object	Definition Error object returned upon a failure. Constraints N/A

**Table 6** NetworkInterface
Parameter	Type	Description
subnet_id	String	Definition CloudDCN subnet ID, which is obtained from the CloudDCN cloud network. Constraints N/A Range N/A Default Value N/A
ipv4_address	String	Definition Private IPv4 address of an elastic network interface. Constraints N/A Range N/A Default Value N/A

**Table 7** Tag
Parameter	Type	Description
key	String	Definition Tag key. Constraints N/A Range Cannot be empty and cannot start or end with spaces. Maximum length: 128 characters. Can contain letters, digits, and spaces in UTF-8 format. Can contain the following special characters: _.:=+-@ Cannot start with _sys_. Default Value N/A
value	String	Definition Tag value. Constraints N/A Range Can be null but not the default. Max characters: 255. Use letters, digits, and spaces in UTF-8 format. Can contain the following special characters: _.:/=+-@ Default Value N/A

**Table 8** Image
Parameter	Type	Description
id	String	Definition Image ID. Constraints N/A Range The value is in UUID format. Default Value N/A
name	String	Definition Image name. Constraints N/A Range N/A Default Value N/A
os_type	String	Definition Image OS type. Constraints N/A Range Linux Windows Other Default Value N/A

**Table 9** ErrorStatus
Parameter	Type	Description
error_code	String	Definition Error code.
error_msg	String	Definition Error description.
error_type	String	Definition Error type. Constraints N/A Range create_instance_error: Instance creation error delete_instance_error: Instance deletion error reinstall_error: OS reinstallation error modify_ip_error: IP address change error verify_server_error: Server verification error delete_server_error: Server deletion error Default Value N/A

**Table 10** PageInfo
Parameter	Type	Description
next_marker	String	Definition Query address of the next page. Constraints N/A Range N/A Default Value N/A
previous_marker	String	Definition Query address of the previous page. Constraints N/A Range N/A Default Value N/A
current_count	Integer	Definition Number of records returned on this page. Constraints N/A Range N/A Default Value N/A

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code.
error_msg	String	Definition Error description.

Status code: 401

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code.
error_msg	String	Definition Error description.

Status code: 429

**Table 13** Response body parameters
Parameter	Type	Description
-	String

Status code: 500

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code.
error_msg	String	Definition Error description.

Example Requests

Querying the instance list

GET https://{endpoint}/v1/{project_id}/instances

Example Responses

Status code: 200

The instance list is displayed by page.

{
  "instances" : [ {
    "id" : "0195f996-79c5-7d34-a98e-3a96f7926d96",
    "name" : "host-0403-199",
    "vpc_id" : "31434907-0817-4acc-9a59-c44cf157303b",
    "network_interfaces" : [ {
      "subnet_id" : "",
      "ipv4_address" : "192.168.27.57"
    } ],
    "image" : {
      "id" : "e66a19b0-8c94-4b03-9f4d-4fbd676bcbf0",
      "name" : "test-lsy\nUbuntu 22.04 server 64bit",
      "os_type" : "Linux"
    },
    "description" : "",
    "state" : "terminated",
    "user_data" : "",
    "server_id" : "0195f996-79c5-7d34-a98e-3a96f7926d96",
    "created_at" : "",
    "updated_at" : "2025-07-11T17:07:05+08:00",
    "launched_at" : "2025-04-03T10:59:03+08:00",
    "error" : {
      "error_code" : "iMetal.0099",
      "error_msg" : "failed to reinstall os, create reinstall job on Jarvis failed",
      "error_type" : "reinstall_error"
    }
  } ],
  "page_info" : {
    "next_marker" : "01981672-2e82-7d8a-a315-3f686155a815",
    "previous_marker" : "",
    "current_count" : 92
  },
  "count" : 92
}

Status Codes

Status Code	Description
200	The instance list is displayed by page.
400	Invalid request parameter.
401	The request is not authenticated.
429	The request is overloaded.
500	Internal server error.