Querying the List of Physical Servers

Function

This API is used to query the list of physical servers.

Calling Method

For details, see Calling APIs.

URI

GET /v1/{project_id}/physicalservers

**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
manage_state	No	String	Definition Server management status. Constraints N/A Range onboard: The server is being onboarded into a rack. You can place an order and complete the LLD design. ready: The delivery is complete, including hardware installation, network commissioning, server initialization, software commissioning, and transfer-to-maintenance acceptance. in-use: The iMetal server is provisioned and in use. frozen: Resources are frozen due to arrears. offboarding: The server is being removed from the rack. Default value N/A
marker	No	String	Definition ID of the last record on the previous page. Constraints N/A Range N/A Default Value N/A
limit	No	Integer	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 10

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
servers	Array of PhysicalServer objects	Definition Pagination of the server list. Constraints N/A
page_info	PageInfo object	Definition Pagination information. Constraints N/A
count	Integer	Definition The total number of servers. Constraints N/A Range N/A Default Value N/A

**Table 5** PhysicalServer
Parameter	Type	Description
id	String	Definition Server ID. Constraints N/A Range The value is in UUID format. Default Value N/A
name	String	Definition Name of a physical server, which is used as the hostname when an instance is created. Constraints N/A Range N/A Default Value N/A
project_id	String	Definition Project ID. Constraints N/A Range Project ID of the account. Default Value N/A
domain_id	String	Definition Tenant ID. Constraints N/A Range N/A Default Value N/A
manage_state	String	Definition Server management status. Constraints N/A Range onboard: The server is being onboarded into a rack. You can place an order and complete the LLD design. ready: The delivery is complete, including hardware installation, network commissioning, server initialization, software commissioning, and transfer-to-maintenance acceptance. in-use: The iMetal server is provisioned and in use. frozen: Resources are frozen due to arrears. offboarding: The server is being removed. Default Value N/A
power_state	String	Definition Power supply status. The power_state value changes according to different operations and events. The common status transition process is as follows: Power-on process: off > powering-on > on Power-off process: on > powering-off > off Reboot process: on > rebooting > on on: The power of a node is turned on, the hardware is powered on, and the OS is running or can be started normally. The node can execute computing tasks and provide services for upper-layer applications. off: The power of a node is turned off, the power supply to the hardware is cut off, and all components are not working. The node cannot execute any computing tasks. rebooting: A node is being rebooted, which means the node is powered off and then powered on. During this process, the hardware is initialized and the OS is started. powering-on: When the node is being powered on, the hardware is powered on, but the OS may not be started. powering-off: The node is being powered off. The OS performs some cleanup operations, such as saving data and stopping services, and then cuts off the power supply to the hardware. Constraints N/A Range Default Value N/A
health_state	String	Definition Hardware health status. Constraints N/A Range OK Warning Critical Unknown The system detects potential problems or minor exceptions. The server can still run properly, but the risk increases. The system detects a severe hardware fault or an extreme exception. The problem has affected the stability, performance, or availability of the server. The health status cannot be detected. The status is unknown. Default Value N/A
onboard_time	String	Definition Onboarding 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
location	Location object	Definition Location of the physical server. Constraints N/A
hardware_attributes	HardwareSummary object	Definition Hardware overview information, including the server manufacturer, model, and serial number. Constraints N/A
tags	Array of Tag objects	Definition Tags. Constraints N/A
error	ErrorStatus object	Definition Error object returned upon a failure. Constraints N/A

**Table 6** Location
Parameter	Type	Description
dc	String	Definition Data center name. Constraints N/A Range Maximum length: 256 bytes. Only letters (case-sensitive), digits, underscores (_), hyphens (-), and periods (.) are allowed. Default Value N/A
rack	String	Definition Cabinet name. Constraints N/A Range Maximum length: 128 bytes. Only letters (case-sensitive), digits, underscores (_), hyphens (-), and periods (.) are allowed. It cannot start with hyphens (-) or periods (.) Default Value N/A
unit	String	Definition Rack U space. Constraints N/A Range Maximum length: 128 characters. Default Value N/A

**Table 7** HardwareSummary
Parameter	Type	Description
sn	String	Definition serial number Constraints N/A Range N/A Default Value N/A
manufacturer	String	Definition Manufacturer. Constraints N/A Range N/A Default Value N/A
model	String	Definition Model. Constraints N/A Range N/A Default Value N/A
main_board_manufacturer	String	Definition Mainboard vendor. Constraints N/A Range N/A Default Value N/A
main_board_serial_number	String	The mainboard serial number.

**Table 8** 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 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 list of physical servers

GET https://{endpoint}/v1/{project_id}/physicalservers?marker={marker}&limit={limit}

Example Responses

Status code: 200

Physical servers are returned by page.

{
  "servers" : [ {
    "id" : "0195d690-cfd4-7303-a1e1-707f2f863921",
    "name" : "test-host-102",
    "project_id" : "e750c9499ffb4244add7398a0af4f215",
    "domain_id" : "aef171e13fe24458a819bb42870571d9",
    "manage_state" : "ready",
    "power_state" : "",
    "health_state" : "",
    "onboard_time" : "2025-03-27T15:46:09.492642+08:00",
    "location" : {
      "dc" : "Room_room_003",
      "rack" : "cabinet_room_003_1",
      "unit" : "SN_26_151_241_102"
    },
    "hardware_attributes" : {
      "sn" : "SN_26_151_241_102",
      "manufacturer" : "Huawei",
      "model" : "2288H v108"
    },
    "tags" : [ {
      "key" : "2",
      "value" : "3"
    } ],
    "error" : {
      "error_code" : "",
      "error_msg" : "inspect imetal job failed, please contact oncall",
      "error_type" : "verify_server_error"
    }
  } ],
  "page_info" : {
    "next_marker" : "0197f36d-d84f-7d92-8d00-dd29b81b9498",
    "current_count" : 1000
  },
  "count" : 1763
}

Status Codes

Status Code	Description
200	Physical servers are returned by page.
400	Invalid request parameter.
401	The request is not authenticated.
429	The request is overloaded.
500	Internal server error.