Batch Querying 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** URI parameter
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
manage_state	No	String	Definition Server management status. Constraints N/A Range onboard: The server is being provisioned. 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 server is provisioned and in use. frozen: Resources are frozen due to arrears. offboarding: The server is being removed. 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 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 10

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
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 Its 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 The project ID. Constraints N/A Range The project ID of the account Default Value N/A
domain_id	String	Definition domain ID Constraints N/A Range N/A Default Value N/A
manage_state	String	Definition Server management status. Constraints N/A Value Range onboard: The server is being provisioned. 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 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 Constraints N/A Range 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. Example scenarios: After a user creates and activates a node in Ironic or powers on a node, the power_state value of the node changes to power on. When a node is under maintenance or is no longer used, the administrator can power off the node. In this case, power_state is power off. When an administrator uses the Ironic API to reboot a node, its power_state changes to rebooting during the process. After an administrator sends a power-on instruction, the node enters the powering on state. The power_state value changes to power on when the OS has been started. After an administrator sends a power-off instruction, the node enters the powering off state. The power_state value changes to off when the power supply is completely turned off. Default Value N/A
health_state	String	Definition Hardware health status. Constraints N/A Range OK Warning Critical Unknown Default Value N/A
onboard_time	String	Definition Provisioning 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 Tag. 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 Equipment room name. Constraints N/A Range Maximum length: 256 bytes. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed. Default Value N/A
rack	String	Definition Rack name. Constraints N/A Range Maximum length: 128 bytes. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed. It cannot start with hyphens (-) or periods (.). Default Value N/A
unit	String	Definition Rack unit (U) Constraints N/A Range Maximum length: 128 bytes 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

**Table 8** 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 9** 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 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 The number of items 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. 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 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: 429

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

Status code: 500

**Table 14** 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 Request

Request for querying the list of physical servers

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

Example Response

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"
    },
    "ops_result" : "InspectError",
    "az_id" : "",
    "region_id" : "",
    "bmc_firmware_version" : ""
  } ],
  "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.