Help Center/ Workspace/ API Reference/ Workspace APIs/ Desktop Pools/ This interface is used to query desktop information in a desktop pool

Updated on 2025-07-14 GMT+08:00

View PDF

This interface is used to query desktop information in a desktop pool

Function

This interface is used to query desktop information in a desktop pool.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

GET /v2/{project_id}/desktop-pools/{pool_id}/desktops

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID.
pool_id	Yes	String	Specifies the desktop pool ID.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
inconsistent_type	No	String	This type is used to filter desktops whose specifications are different from those of the desktop pool. PRODUCT: Searches for desktops whose productID is different from the desktop pool package ID. IMAGE: Searches for desktops whose imageID is different from the desktop pool image ID.
offset	No	Integer	Where the pagination query starts. The value starts from 0.
limit	No	Integer	Limits the quantity of returned desktops in pagination query. The value ranges from 0 to 100. The default value is 10.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	User token. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
pool_desktops	Array of PoolDesktopsDetailInfo objects	Pooled desktop details.
total_count	Integer	Total number of desktops.
on_demand_desktops_num	Integer	Total number of pay-per-use desktops.
period_desktops_num	Integer	Total number of yearly/monthly desktops.

**Table 5** PoolDesktopsDetailInfo
Parameter	Type	Description
desktop_id	String	Desktop ID.
computer_name	String	Desktop name.
os_host_name	String	Computer name in the OS.
addresses	Map<String,Array<AddressInfo>>	Desktop IP addresses.
ip_addresses	Array of strings	IP addresses.
ipv4	String	IPv4 address of the computer in the OS.
ipv6	String	IPv6 address of the computer in the OS.
user_list	Array of strings	User list.
user_group_list	Array of strings	User group list.
desktop_type	String	Desktop type. DEDICATED: a dedicated desktop
resource_type	String	resource_type field, which indicates dedicated desktop (DEDICATED_DESKTOP), pooled desktop (POOLED_DESKTOP), rendering desktop (RENDER_DESKTOP), exclusive host (EXCLUSIVE_HOST), or shared desktop (SHARED_DESKTOP).
metadata	Map<String,String>	Desktop metadata. charging_mode: billing mode of the package. 1 indicates yearly/monthly billing, and 0 indicates pay-per-use billing. image_name: name of the image used to create a desktop bill_resource_id: billing resource ID of the image metering.image_id: image ID metering.resourcespeccode: desktop resource code metering.resourcetype: desktop resource type os_bit: number of bits of the OS. The value can be 32 or 64. os_type: OS type. The value can be Linux, Windows, or Others. desktop_os_version: OS version
flavor	FlavorInfo object	Product information.
status	String	Desktop status.
task_status	String	Task status. scheduling: Resources are being scheduled. block_device_mapping: The disk is being prepared. networking: The network is being prepared. spawning: The task is being created internally. rebooting: The system is being restarted. reboot_pending: The task of system restart is being delivered. reboot_started: The system is being restarted internally. rebooting_hard: The system is being force restarted. reboot_pending_hard: The task of force restart is being delivered. reboot_started_hard: The system is being force restarted internally. rebuilding: The system is being rebuilt. rebuild_block_device_mapping: The system is being rebuilt and disks are being prepared. rebuild_spawning: The system is being rebuilt internally. migrating: Live migration is being performed. resize_prep: The specifications are to be adjusted. resize_migrating: The specifications are being adjusted and the migration is in progress. resize_migrated: The specifications are being adjusted and the migration has been completed. resize_finish: The specifications have been adjusted. resize_reverting: The specification adjustment is being rolled back. powering-off: The system is being powered off. powering-on: The system is being powered on. deleting: Deleting... deleteFailed: Deletion failed. updating: Updating... desktopNetworkChanging: The network is being switched.
in_maintenance_mode	Boolean	Whether the desktop is in maintenance mode. The options are true (yes) and false (no).
created	String	Time when a desktop is created.
security_groups	Array of SecurityGroupInfo objects	Desktop security group.
login_status	String	Login status of a desktop. UNREGISTER: The desktop is not registered. After the desktop is started, it is automatically registered. After the desktop is shut down, it is unregistered. REGISTERED: The desktop has been registered and is waiting for user connections. CONNECTED: A user has logged in to a desktop and is using it. DISCONNECTED: The desktop is disconnected from the client because the client window is closed or the networking between the client and desktop is interrupted.
user_name	String	User to whom the desktop belongs.
attach_user_infos	Array of AttachInstancesUserInfo objects	List of users to whom desktops have been assigned.
product_id	String	Product ID.
share_resource_sku	String	Desktop collaboration resource SKU code.
root_volume	VolumeDetail object	System disk.
data_volumes	Array of VolumeDetail objects	Data disks.
user_group	String	User group to which the desktop user belongs. sudo: Linux administrator group. default: Default Linux user group. administrators: Windows administrator group. Administrators have full access to the desktop and can make any required changes except for forbidden operations. users: standard Windows user group. Standard users can use most software programs and change system settings that do not affect other users.
availability_zone	String	AZ.
site_type	String	Site type.
site_name	String	Site name.
product	ProductInfo object	Product information.
ou_name	String	Name of the OU to which the desktop is added during desktop creation.
os_version	String	OS version.
sid	String	SID.
order_id	String	Order ID of a yearly/monthly product.
tags	Array of Tag objects	Desktop tags.
is_support_internet	Boolean	Whether to enable the Internet access. The options are true (yes) and false (no).
internet_mode	String	Network access mode. NAT: indicates the NAT Internet access mode EIP: indicates the EIP Internet access mode BOTH: Both the Internet and EIP access modes are supported.
internet_mode_list	Array of strings	Network access modes of desktops.
is_attaching_eip	Boolean	Specifies whether an EIP is being bound to the desktop.
attach_state	String	Allocation status. ATTACHED: allocated. UNATTACH: Unassigned indicates that the session is not associated. DEATTACHED: The VM has been unassigned. ATTACHING: The VM is being allocated. DEATTACHING: The VM is being unassigned. ATTACHFAIL: The allocation fails. DEATTACHFAIL: The VM fails to be unassigned. WAITING: waiting to be assigned. This state describes the intermediate state from batch assignment (unassignment) to transfer to assignment (unassignment). In addition, this state facilitates the independence of a single association process. ATTACH_FAIL_CAN_ATTACH_AGAIN: The VM fails to be assigned and can be associated again. DEATTACH_FAIL_CAN_DEATTACH_AGAIN: The VM fails to be unassigned and can be unassigned again.
enterprise_project_id	String	Enterprise project ID.
subnet_id	String	Subnet ID of the desktop.
bill_resource_id	String	Billing resource ID of the desktop.
process	Integer	Desktop task progress. The value ranges from 0 to 100, or is null. null indicates that there is no task on the desktop. The value from 0 to 100 indicates the task progress percentage.
root_resource_id	String	Root resource ID of the desktop instance.
hour_package_info	HourPackageInfo object	Hourly-billed desktop package details.
inconsistent_types	Array of strings	Different specification type between the desktop and the desktop pool: PRODUCT: different product IDs IMAGE: different image IDs

**Table 6** AddressInfo
Parameter	Type	Description
addr	String	IP address.
version	String	IP address type. The value can be 4 (IPv4) or 6 (IPv6).
OS-EXT-IPS-MAC:mac_addr	String	MAC address.
OS-EXT-IPS:type	String	IP address assignment method. -fixed: a private IP address -floating: a floating IP address

**Table 7** FlavorInfo
Parameter	Type	Description
id	String	Flavor ID of the desktop.
links	Array of FlavorLinkInfo objects	Shortcut link marker information of the corresponding desktop flavor.

**Table 8** FlavorLinkInfo
Parameter	Type	Description
rel	String	Shortcut link marker name.
hrel	String	Corresponding shortcut link.

**Table 9** SecurityGroupInfo
Parameter	Type	Description
id	String	Security group ID.
name	String	Security group name.

**Table 10** AttachInstancesUserInfo
Parameter	Type	Description
user_id	String	If type is set to USER, enter the user ID. If type is set to GROUP, enter the user group ID. The backend service checks whether the group ID exists.
user_name	String	Name of the object assigned with a desktop. If type is set to USER, enter the username. If type is set to GROUP, enter the user group name. If type is set to USER, the value is the username of the desktop user. After the desktop is assigned, the user can log in to the desktop. Only letters, digits, hyphens (-), and underscores (_) are allowed. When the domain type is LITE_AD, the value contains 1 to 20 characters starting with a letter. When the domain type is LOCAL_AD, the value contains 1 to 64 characters starting with a letter or digit. A Windows desktop username can contain a maximum of 20 characters, and a Linux desktop username can contain a maximum of 64 characters. The backend service checks whether the username exists. The username cannot be the same as the desktop name. If type is set to GROUP, the value can contain only letters, digits, hyphens (-), and underscores (_).
user_group	String	Specifies the user group to which the desktop user belongs. sudo: Linux administrator group. default: default Linux user group. administrators: Windows administrator group. Administrators have full access to the desktop and can make any required changes except for forbidden operations. users: standard Windows user group. Standard users can use most software programs and change system settings that do not affect other users.
type	String	Object type. Options: USER: user GROUP: user group

**Table 11** VolumeDetail
Parameter	Type	Description
type	String	Desktop data disk type, which must be the same as the disk type provided by the system. SAS: High I/O SSD: Ultra-high I/O
size	Integer	Disk capacity in GB.
device	String	Directory to which the disk is mounted.
id	String	Unique ID of the disk.
volume_id	String	Disk ID.
bill_resource_id	String	Billing resource ID of the disk.
create_time	String	Time when the disk was created.
display_name	String	Disk name.
resource_spec_code	String	Specifications.

**Table 12** ProductInfo
Parameter	Type	Description
product_id	String	Product ID.
flavor_id	String	Specifications ID.
type	String	Product type. BASE: basic product package. OS is the only commercial software product in the package. Only this type of package can be used for private images.
cpu	String	CPU.
memory	String	Memory.
descriptions	String	Product description.
charge_mode	String	Billing type of the package. 1 indicates yearly/monthly billing, and 0 indicates pay-per-use billing.
architecture	String	Product architecture.
is_gpu	Boolean	Whether the specifications are of the GPU type.
package_type	String	Package type. ultimate: ultimate edition enterprise: enterprise edition general: general office edition workstation: cloud workstation edition dedicated: dedicated edition solver: solver edition agile: agile office edition
system_disk_type	String	System disk type.
system_disk_size	String	System disk size.
contain_data_disk	Boolean	Whether data disks are included in the package billing. off indicates no.
resource_type	String	Resource type.
cloud_service_type	String	Cloud service type.
volume_product_type	String	Disk type.
status	String	The status can be normal (by default, on sale), sellout (sold out), and abandon (unavailable).

**Table 13** Tag
Parameter	Type	Description
key	String	Specifies the tag key. This parameter cannot be left blank and can contain a maximum of 128 Unicode characters. The value can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). The value cannot contain the following characters: =*<>,\|/.
value	String	Value of a tag, which can contain a maximum of 43 Unicode characters. The value can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). The value cannot contain the following characters: =*<>,\|/.

**Table 14** HourPackageInfo
Parameter	Type	Description
root_order_id	String	Root order ID of the hourly-billed package.
package_resource_id	String	Resource ID of the hourly-billed package.
package_instance_id	String	Instance ID of the hourly-billed package.
package_spec_code	String	specCode of the hourly-billed package.
combined_product_type_code	String	resourceTypeCode of the offering portfolio.
use_up_policy	String	Hourly-billed package exhaustion policy. SHUTDOWN_OR_HIBERNATE: automatic shutdown or hibernation; PAY_PER_USE: pay-per-use billing
package_duration	Integer	Total duration of the hourly-billed package.
use_duration	Integer	Used duration of the hourly-billed package.

Status code: 400

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error description.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 401

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error description.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 403

**Table 17** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error description.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 404

**Table 18** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error description.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 409

**Table 19** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error description.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 500

**Table 20** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error description.
error_detail	String	Error details.
encoded_authorization_message	String	Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Example Requests

/v2/bcae3e673fd04716a3b9dacdf58ca336/desktop-pools/a130ab3a-72bf-4b71-baa9-af4987c8e338/desktops

Example Responses

Status code: 200

Response to the request for querying users and user groups authorized by the desktop pool.

{
  "pool_desktops" : [ {
    "desktop_id" : "ffb9a973-da80-4f58-9f71-5c83c229b3f9",
    "computer_name" : "desktop-mwaxmga",
    "os_host_name" : "desktop-mwaxmga",
    "addresses" : {
      "3596ca3f-0ea0-48ff-8010-3c87e72d9726" : [ {
        "osextipsmacmacAddr" : "fa:16:3e:36:31:9a",
        "osextipstype" : "fixed",
        "addr" : "172.16.11.116",
        "version" : "4",
        "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:36:31:9a",
        "OS-EXT-IPS:type" : "fixed"
      } ],
      "016842ec-3d5e-41bd-8ef6-6b34acbec67e" : [ {
        "osextipsmacmacAddr" : "fa:16:3e:98:4a:0c",
        "osextipstype" : "fixed",
        "addr" : "172.26.204.142",
        "version" : "4",
        "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:98:4a:0c",
        "OS-EXT-IPS:type" : "fixed"
      } ]
    },
    "ip_addresses" : [ "172.16.11.116", "172.26.204.142" ],
    "ipv4" : "172.16.11.116",
    "ipv6" : "",
    "user_list" : [ ],
    "user_group_list" : [ ],
    "desktop_type" : "POOLED",
    "metadata" : {
      "image_name" : "WKS_WIN1064_UserImage",
      "metering.resourcespeccode" : "c7.large.2.win",
      "charging_mode" : "0",
      "metering.image_id" : "cc3bbc0b-9441-461b-b80b-48c52f3aed08",
      "metering.resourcetype" : "1",
      "os_type" : "Windows",
      "os_bit" : "64",
      "bill_resource_id" : "ffb9a973-da80-4f58-9f71-5c83c229b3f9.workspace",
      "desktop_os_version" : "Version2009(OS Build 19041.1288)"
    },
    "flavor" : {
      "id" : "c7.large.2",
      "links" : [ ]
    },
    "status" : "ACTIVE",
    "task_status" : "",
    "in_maintenance_mode" : false,
    "created" : "2025-05-22T09:48:55.864Z",
    "login_status" : "REGISTERED",
    "product_id" : "workspace.x86.ultimate.large2",
    "root_volume" : {
      "type" : "SAS",
      "size" : 80,
      "device" : "/dev/sda",
      "id" : "f4fc32db36f111f0ade6fa163e5a5e29",
      "volume_id" : "c6367195-1231-49e4-bb89-c2201d4c1986",
      "bill_resource_id" : "c6367195-1231-49e4-bb89-c2201d4c1986",
      "create_time" : "2025-05-22T09:48:47.366Z",
      "display_name" : "desktop-mwaxmga-volume-0000",
      "resource_spec_code" : "workspace.volume.high"
    },
    "data_volumes" : [ {
      "type" : "SAS",
      "size" : 10,
      "device" : "/dev/sdb",
      "id" : "f4fe25e536f111f0ade6fa163e5a5e29",
      "volume_id" : "14289779-6668-402a-9cfb-2218a4b95507",
      "bill_resource_id" : "14289779-6668-402a-9cfb-2218a4b95507",
      "create_time" : "2025-05-22T09:48:47.378Z",
      "display_name" : "desktop-mwaxmga-volume-0001",
      "resource_spec_code" : "workspace.volume.high"
    } ],
    "availability_zone" : "cn-north-7c",
    "site_type" : "CENTER",
    "site_name" : "Huawei Cloud Central Site",
    "product" : {
      "product_id" : "workspace.x86.ultimate.large2",
      "flavor_id" : "c7.large.2",
      "type" : "BASE",
      "cpu" : "2",
      "memory" : "4096",
      "descriptions" : "Ultimate | 2 vCPUs | 4 GB memory",
      "charge_mode" : "1",
      "architecture" : "x86",
      "is_gpu" : false,
      "package_type" : "ultimate",
      "system_disk_type" : "SAS",
      "system_disk_size" : "140",
      "contain_data_disk" : false,
      "resource_type" : "hws.resource.type.workspace.desktop",
      "cloud_service_type" : "hws.service.type.vdi",
      "volume_product_type" : "workspace",
      "status" : "normal"
    },
    "os_version" : "Version2009(OS Build 19041.1288)",
    "sid" : "4f65a743-283c-4612-bce4-7d4c9a9c3bfe",
    "tags" : [ ],
    "is_support_internet" : true,
    "internet_mode_list" : [ "WORKSPACE_BANDWIDTH" ],
    "is_attaching_eip" : false,
    "attach_state" : "UNATTACH",
    "enterprise_project_id" : "0",
    "subnet_id" : "c7f30df4-f3ac-4807-9599-18950b05455f",
    "bill_resource_id" : "ffb9a973-da80-4f58-9f71-5c83c229b3f9",
    "inconsistent_types" : [ ]
  } ],
  "total_count" : 1,
  "on_demand_desktops_num" : 1,
  "period_desktops_num" : 0
}

Status Codes

Status Code	Description
200	Response to the request for querying users and user groups authorized by the desktop pool.
400	The request cannot be understood by the server due to malformed syntax.
401	Authentication failed.
403	No operation permissions.
404	No resources found.
409	Operation conflict.
500	An internal service error occurred. For details about the error code, see the error code description.