Batch Querying Instances

Function

This API is used to batch query instances.

Calling Method

For details, see Calling APIs.

URI

GET /v1/{project_id}/instances

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition The project ID. Constraints N/A Range The 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 The value range is from 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 1000, 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 only try to reinstall the OS. Other operations are not supported and related resources are cleared. Default Value N/A
instance_id	No	String	Definition Instance IDs. The value can be an array consisting of multiple instance IDs. Constraints N/A Range A maximum of 100 IDs are supported. The IDs are separated by commas (,), 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 are supported. The IDs are separated by commas (,), for example, uuid1,uuid2,uuid3. Default Value N/A

Request Parameters

**Table 3** Request header parameter
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	The 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 about an iMetal server. Constraints An iMetal server can contain a maximum of two network interfaces, 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 Tag. Constraints N/A
image	Image object	Definition Server image information. Constraints N/A
description	String	Definition Description of the cloud server. Constraints N/A Range N/A Default Value Empty string
state	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 only try to reinstall the OS. Other operations are not supported and related resources are cleared. Default Value N/A
metadata	Table 9 object	-
user_data	String	Definition Custom user data to be injected into the instance during instance creation. Constraints N/A Range The content of user_data must be encoded with base64. The maximum size of the content to be injected (before encoding) is 32 KB. Default Value N/A
server_id	String	Definition Server ID. Constraints N/A Range Its 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 subnet id 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 The value cannot be empty and cannot start or end with spaces. A maximum of 128 characters are supported. The value can contain letters, digits, and spaces in UTF-8 format. The value can contain the following special characters: _.:=+-@ The value cannot start with sys. Default Value N/A
value	String	Definition Tag value. Constraints N/A Range The value can contain a maximum of 255 characters. It can be empty but cannot be the default. The value can be letters, digits, and spaces in UTF-8 format. The value 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** metadata
Parameter	Type	Description
{Custom key}	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 contains only uppercase letters, lowercase letters, spaces, digits, hyphens (-), underscores (_), colons (:), and decimal points (.). A metadata value consists of a maximum of 255 characters. Default Value N/A

**Table 10** ErrorStatus
Parameter	Type	Description
error_code	String	Definition Error code. Constraints N/A Range N/A Default Value N/A
error_msg	String	Definition Error message. Constraints N/A Range N/A Default Value N/A
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 exception Default Value N/A

**Table 11** 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 The number of items returned on this page. Constraints N/A Range N/A Default Value N/A

Status code: 400

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code. Constraints N/A Range N/A Default Value N/A
error_msg	String	Definition Error message. Constraints N/A Range N/A Default Value N/A

Status code: 401

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code. Constraints N/A Range N/A Default Value N/A
error_msg	String	Definition Error message. Constraints N/A Range N/A Default Value N/A

Status code: 429

**Table 14** Response body parameter
Parameter	Type	Description
-	String	-

Status code: 500

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code. Constraints N/A Range N/A Default Value N/A
error_msg	String	Definition Error message. Constraints N/A Range N/A Default Value N/A

Example Requests

Request for batch querying instances

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.