All Products
Search
Document Center

Elastic Desktop Service:DescribeDesktops

Last Updated:Aug 19, 2026

Queries the details of cloud computers.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecd:DescribeDesktops

get

*All Resource

*

None None

Request parameters

Parameter

Type

Required

Description

Example

BusinessChannel

string

No

The business channel. Valid values:

Valid values:

  • Enterprise :

    Enterprise Edition.

  • AGENTIC_CLOUD_COMPUTER :

    Agentic cloud computer.

  • Business :

    Business Edition.

  • Lincore_team :

    Lincore Team Edition.

Enterprise

RegionId

string

Yes

The region ID. You can call DescribeRegions to query the regions supported by Elastic Desktop Service.

cn-hangzhou

GroupId

string

No

The cloud computer pool ID.

dg-boyczi8enfyc5****

DesktopStatus

string

No

The cloud computer status.

Valid values:

  • Stopped :

    Stopped.

  • Starting :

    Starting.

  • Rebuilding :

    Rebuilding.

  • Running :

    Running.

  • Stopping :

    Stopping.

  • Expired :

    Expired.

  • Deleted :

    Deleted.

  • Pending :

    Pending.

Running

MaxResults

integer

No

The maximum number of entries per page in a paged query. This parameter is used for paging.

10

NextToken

string

No

The pagination token for the next query. An empty value indicates that no more results exist.

caeba0bbb2be03f84eb48b699f0a4883

UserName

string

No

The username.

Alice

DesktopName

string

No

The cloud computer name.

DemoComputer01

DirectoryId

string

No

The directory ID, which is the same as the office network ID.

cn-hangzhou+dir-363353****

OfficeSiteId

string

No

The office network ID.

cn-hangzhou+dir-363353****

OfficeSiteName

string

No

The office network name.

default

PolicyGroupId

string

No

The cloud computer policy ID.

system-all-enabled-policy

ChargeType

string

No

The billing method of the cloud computer.

Valid values:

  • PostPaid :

    Pay-as-you-go. [Default value]

  • PrePaid :

    Subscription.

PostPaid

ExpiredTime

string

No

The expiration time of the subscription cloud computer.

2022-12-31T15:59:59Z

ProtocolType

string

No

The protocol type.

Valid values:

  • HDX :

    HDX protocol.

  • ASP :

    Alibaba Cloud-proprietary ASP protocol. [Recommended]

ASP

DesktopId

array

No

The cloud computer IDs. You can specify 1 to 100 IDs.

ecd-gx2x1dhsmucyy****

string

No

The cloud computer ID.

ecd-gx2x1dhsmucyy****

EndUserId

array

No

The list of authorized users of the cloud computer. You can specify 1 to 100 users.

Note

Only one user can connect to and use the cloud computer at a time.

alice

string

No

The authorized user of the cloud computer.

alice

ExcludedEndUserId

array

No

The list of authorized users to exclude. You can specify 1 to 100 users.

andy

string

No

The authorized user to exclude.

andy

FilterDesktopGroup

boolean

No

Specifies whether to exclude pooled cloud computers (cloud computers in a cloud computer pool).

Valid values:

  • true :

    Exclude pooled cloud computers. [Default value]

  • false :

    Do not exclude pooled cloud computers.

false

ManagementFlag

string

No

The management flag.

Valid values:

  • Migrating :

    Migrating.

  • Updating :

    Changing specifications.

  • NoFlag :

    No flag.

NoFlag

QueryFotaUpdate

boolean

No

Specifies whether to query the image version information of the cloud computer.

Valid values:

  • true :

    Query the image upgrade information of the cloud computer.

  • false :

    Do not query the image upgrade information of the cloud computer. [Default value]

false

Tag

array<object>

No

The tags. A tag consists of a key-value pair and is used to identify resources. You can use tags to group and manage cloud computers for easier searching and batch operations. For more information, see Use tags to manage cloud computers.

object

No

The tag key-value pair. You can specify 1 to 20 key-value pairs for each cloud computer. Each tag key can have only one tag value.

Key

string

No

The tag key. If you specify Tag, Key is required. The tag key cannot exceed 128 characters in length, cannot start with aliyun or acs:, cannot contain http:// or https://, and cannot consist of only spaces.

TestKey

Value

string

No

The tag value. The tag value cannot exceed 128 characters in length, cannot start with aliyun or acs:, and cannot contain http:// or https://.

TestValue

SnapshotPolicyId

string

No

The snapshot policy ID.

sp-hb12mclyne09xw***

OnlyDesktopGroup

boolean

No

Specifies whether to query only pooled cloud computers (cloud computers in a cloud computer pool).

true

DesktopGroupId

string

No

The cloud computer pool ID. If DesktopId is specified, DesktopGroupId is ignored. If DesktopId is empty, the system retrieves the IDs of all cloud computers in the cloud computer pool specified by DesktopGroupId.

dg-2i8qxpv6t1a03****

OsTypes

array

No

The operating system types.

string

No

The operating system types.

Valid values:

  • Linux :

    Linux

  • Windows :

    Windows

Windows

DesktopType

string

No

The cloud computer specifications. You can call DescribeDesktopTypes to query the supported specification IDs.

eds.general.2c8g

ImageId

array

No

The image IDs.

string

No

The image ID.

m-2g65ljy3ynrdq****

DesktopStatusList

array

No

The list of cloud computer statuses.

string

No

The cloud computer status.

Valid values:

  • Stopped :

    Stopped.

  • Starting :

    Starting.

  • Rebuilding :

    Rebuilding.

  • Running :

    Running.

  • Stopping :

    Stopping.

  • Expired :

    Expired.

  • Deleted :

    Deleted.

  • Pending :

    Pending.

Stopped

GpuInstanceGroupId

string

No

The elastic GPU pool ID.

gp-0bm2iz1v6m6nx****

QosRuleId

string

No

The Internet bandwidth throttling rule ID.

qos-5605u0gelk200****

SubPayType

string

No

The purchase method of the cloud computer.

Valid values:

  • duration :

    Duration-based package. [Allowlist]

  • postPaid :

    On-demand purchase.

  • monthPackage :

    Monthly purchase (120 hours/250 hours).

  • prePaid :

    Monthly purchase (unlimited hours).

monthPackage

ResourceGroupId

string

No

The resource group ID.

rg-4hsvzbbmqdzu3s****

FillResourceGroup

boolean

No

Specifies whether to query resource group information.

true

PageNumber

integer

No

The page number of the current page in a paged query. This parameter is used for paging.

1

PageSize

integer

No

The maximum number of entries per page in a paged query. This parameter is used for paging.

10

MultiResource

boolean

No

Specifies whether multiple resources exist.

false

IncludeAutoSnapshotPolicy

boolean

No

Specifies whether to include automatic snapshot policy information in the response.

No

No

Response elements

Element

Type

Description

Example

object

The collection of returned information.

NextToken

string

The pagination token for the next query. An empty value indicates that no more results exist.

caeba0bbb2be03f84eb48b699f0a4883

RequestId

string

The request ID.

484256DA-D816-44D2-9D86-B6EE4D5BA78C

TotalCount

integer

The total number of cloud desktops.

1

Desktops

array<object>

The details of cloud desktops.

array<object>

The details of cloud desktops.

CreationTime

string

The time when the cloud desktop was created. The time is in the ISO 8601 standard in UTC.

2020-11-06T08:28Z

ChargeType

string

The billing method of the cloud desktop.

Valid values:

  • PostPaid :

    Pay-as-you-go. [Default value]

  • PrePaid :

    Subscription.

PostPaid

DesktopName

string

The cloud computer name.

DemoComputer01

PolicyGroupName

string

The policy name.

All enabled policy

SystemDiskSize

integer

Note

This parameter is in invitational preview and is not publicly available.

0

PolicyGroupId

string

The cloud computer policy ID.

system-all-enabled-policy

DesktopStatus

string

The cloud computer status.

Running

DesktopType

string

The cloud desktop type.

ecd.basic.large

GpuCount

number

The number of GPUs.

1

ProtocolType

string

The protocol type.

Valid values:

  • HDX :

    HDX protocol.

  • ASP :

    Alibaba Cloud proprietary ASP protocol.

ASP

Memory

integer

The memory size. Unit: MiB.

4096

GpuSpec

string

The GPU specifications.

NVIDIA T4

ImageId

string

The image ID.

m-4zfb6zj728hhr****

ImageName

string

The image name before the change.

Windows server 2019 Mainland

DirectoryId

string

The directory ID, which is the same as the workspace ID (OfficeSiteId).

cn-hangzhou+dir-363353****

ManagementFlag

string

The management flag.

Valid values:

  • Migrating :

    Migrating.

  • Updating :

    Changing specifications.

  • NoFlag :

    No flag.

NoFlag

DataDiskCategory

string

Note

This parameter is in invitational preview and is not publicly available.

cloud_auto

SystemDiskCategory

string

Note

This parameter is in invitational preview and is not publicly available.

cloud_auto

NetworkInterfaceId

string

The ID of the secondary ENI created by the cloud desktop service for the RAM or AD user. This value cannot be modified.

123456

OfficeSiteId

string

The office network ID.

cn-hangzhou+dir-363353****

DataDiskSize

string

Note

This parameter is in invitational preview and is not publicly available.

80

DesktopGroupId

string

The ID of the cloud desktop pool to which the cloud desktop belongs. Default value: null.

dg-2i8qxpv6t1a03****

DesktopId

string

The cloud computer ID.

ecd-gx2x1dhsmucyy****

OfficeSiteName

string

The office network name.

default

StartTime

string

The time when the cloud desktop was first started. The time is in the ISO 8601 standard in UTC.

2020-11-06T08:31Z

DirectoryType

string

Note

This parameter is in invitational preview and is not publicly available.

SIMPLE

Cpu

integer

The number of vCPUs.

2

NetworkInterfaceIp

string

The IP address of the secondary ENI created by the cloud desktop service for the RAM or AD user.

192.168.XX.XX

ExpiredTime

string

The expiration time of the subscription cloud desktop. The time is in the ISO 8601 standard in UTC.

2021-12-31T15:59Z

OsType

string

The operating system types.

Windows

ConnectionStatus

string

The connection status of the user.

Valid values:

  • Unknown :

    Unknown.

  • Connected :

    Connected.

  • Disconnected :

    Disconnected.

Disconnected

BundleId

string

The ID of the cloud desktop template used by the cloud desktop.

b-2g65ljy4291vl****

BundleName

string

The name of the cloud desktop template used by the cloud desktop.

TemplateName

OfficeSiteType

string

The account system type of the workspace.

Valid values:

  • SIMPLE :

    Convenience account.

  • AD_CONNECTOR :

    Enterprise AD account.

SIMPLE

HostName

string

The hostname.

testName

Disks

array<object>

The disk information.

object

The disk information.

DiskType

string

The disk type.

Valid values:

  • SYSTEM :

    System cloud disk.

  • DATA :

    Data cloud disk.

SYSTEM

DiskId

string

The disk ID.

d-jedbpr4sl9l37****

DiskSize

integer

The disk size. Unit: GiB.

80

PerformanceLevel

string

The performance level (PL) of the ESSD when the disk is an ESSD.

For more information about the differences between ESSDs at different PLs, see ESSD.

Valid values:

  • PL1 :

    PL1

  • PL0 :

    PL0

  • PL3 :

    PL3

  • PL2 :

    PL2

PL0

DiskCategory

string

The disk type.

  • cloud_efficiency: ultra cloud disk
    • cloud_auto: ultra-fast cloud disk

    • cloud_essd: enhanced SSD (supported only by specific instance types)

Valid values:

  • cloud_efficiency :

    Ultra cloud disk.

  • cloud_auto :

    Ultra-fast cloud disk.

  • cloud_essd :

    Enhanced standard SSD cloud disk. Only specific types support this option.

cloud_auto

Tags

array<object>

The tag information.

object

The tag information.

Key

string

The tag key.

TestKey

Value

string

The tag value.

TestValue

Sessions

array<object>

The user session information of the cloud desktop.

object

The user session information of the cloud desktop.

EndUserId

string

The ID of the user connected to the cloud desktop.

29615820929547****

EstablishmentTime

string

The time when the cloud desktop session was established. The time is in the ISO 8601 standard in UTC.

2021-03-07T08:23Z

ExternalUserName

string

The external username.

Testname

EndUserIds

array

The IDs of authorized users of the cloud desktop.

string

The IDs of authorized users of the cloud desktop.

alice

DowngradeQuota

integer

The number of times the cloud desktop can be downgraded.

3

DowngradedTimes

integer

The number of times the cloud desktop has been downgraded.

0

GpuCategory

integer

Indicates whether the cloud desktop is a GPU-accelerated cloud desktop.

0

GpuDriverVersion

string

The GPU driver version of the cloud desktop.

471.68

ZoneType

string

The type of the zone. Default value: AvailabilityZone, which indicates a regular cloud zone.

AvailabilityZone

FotaUpdate

object

The image version information of the cloud computer.

CurrentAppVersion

string

The version number of the current image on the cloud computer.

0.0.0-D-20220102.000000

NewAppVersion

string

The image version number to which the cloud computer can be upgraded.

0.0.0-R-20220307.190736

ReleaseNote

string

The release note of the image version to which the cloud computer can be upgraded.

Test upgrade package 03-07

Size

integer

The size of the upgrade package. Unit: KB.

108815097

ReleaseNoteEn

string

The English release note of the image version to which the cloud computer can be upgraded.

What's new

ReleaseNoteJp

string

The Japanese release note of the image version to which the cloud computer can be upgraded.

リリースノート

Progress

string

The creation progress of the cloud computer.

100%

VolumeEncryptionEnabled

boolean

Indicates whether disk encryption is enabled.

false

VolumeEncryptionKey

string

The ID of the Key Management Service (KMS) key used for disk encryption. You can call the ListKeys operation to obtain the key ID.

08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****

OfficeSiteVpcType

string

The VPC type of the office network.

Valid values:

  • standard :

    Standard.

  • customized :

    Customized.

  • basic :

    Basic.

basic

Platform

string

The operating system platform information.

Valid values:

  • Ubuntu :

    Ubuntu

  • Windows Server 2022 :

    Windows Server 2022

  • UOS :

    UOS

  • CentOS :

    CentOS

  • Windows Server 2019 :

    Windows Server 2019

  • Windows Server 2016 :

    Windows Server 2016

Ubuntu

SessionType

string

The session type.

Valid values:

  • SINGLE_SESSION :

    Single session.

  • MULTIPLE_SESSION :

    Multiple sessions.

SINGLE_SESSION

ManagementFlags

array

The management flag.

string

The management status of the cloud computer.

Valid values:

  • Migrating :

    Office network migrating.

  • Hibernated :

    Hibernated.

  • UnderMaintenance :

    Under maintenance.

  • MigratingProtocol :

    Protocol migrating.

  • EnterMaintenance :

    Entering maintenance mode.

  • WakingUp :

    Waking up.

  • Updating :

    Upgrading.

  • NoFlag :

    No status.

  • Assigning :

    Assigning user.

  • Hibernating :

    Hibernating.

["NoFlag"]

SnapshotPolicyId

string

The snapshot policy ID.

sp-gi007jgyc3kce****

SnapshotPolicyName

string

The snapshot policy name.

testSnapshotName

BindAmount

integer

The number of concurrent sessions allowed per cloud computer in a multi-session cloud computer pool.

2

PolicyGroupIdList

array

The collection of cloud computer policy IDs.

string

The cloud computer policy ID.

pg-dasffjkdf*****

PolicyGroupNameList

array

The list of cloud computer policy names.

string

The cloud computer policy name.

TestPolicy01

HibernationOptionsConfigured

boolean

Note

This parameter is in invitational preview and is not publicly available.

true

SupportHibernation

boolean

Indicates whether hibernation is supported.

true

HibernationBeta

boolean

Note

This parameter is in invitational preview and is not publicly available.

true

ResourceGroups

array<object>

The list of resource group information.

object

The resource group information.

Name

string

The resource group name.

ResourceGroup01

Id

string

The resource group ID.

rg-4hsvzbbmqdzu3s****

StandardStartTime

string

The start time of the query. The time is in the ISO 8601 standard and in UTC+0, in the format of yyyy-mm-ddthh:mm:ssz.

2025-01-27T02:20:10Z

OsUpdate

object

The operating system update information of the cloud computer.

CheckId

string

The ID of the health check task.

ck-8f2a1b****

PackageCount

integer

The number of pending update patches.

3

Packages

array<object>

The list of system patches.

object

Kb

string

The KB number of the system patch.

KB5032190

Title

string

The vulnerability name.

2021-05 Servicing Stack Update for Windows Server 2019 for x64-based Systems (KB5003243)

Description

string

The NAS file system description.

newDescription

IsLdap

boolean

Indicates whether the directory is an LDAP directory.

DomainType

string

The domain type of the directory to which the cloud computer belongs.

AD

SerialNumber

string

The serial number of the terminal.

96c530bc-6095-4014-8bbc-d461b8ac****

AccountType

string

The account type.

SIMPLE

EntraDomainName

string

The domain name of Microsoft Entra ID.

contoso.onmicrosoft.com

EnvType

string

The environment type. This parameter is not publicly available.

Private

EnvId

string

The environment ID. This parameter is not publicly available.

adifa****

AgentProviderList

array

The list of agents supported by the current cloud computer.

string

The agent supported by the current cloud computer.

Wuying

SubnetId

string

The subnet ID.

vsw-dgea1*****

DesktopDurationList

The list of duration package information for the cloud computer.

PageNumber

integer

The page number of the current page in a paged query.

1

PageSize

integer

The maximum number of rows per page in a paged query.

10

Examples

Success response

JSON format

{
  "NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
  "RequestId": "484256DA-D816-44D2-9D86-B6EE4D5BA78C",
  "TotalCount": 1,
  "Desktops": [
    {
      "CreationTime": "2020-11-06T08:28Z",
      "ChargeType": "PostPaid",
      "DesktopName": "DemoComputer01",
      "PolicyGroupName": "All enabled policy",
      "SystemDiskSize": 0,
      "PolicyGroupId": "system-all-enabled-policy",
      "DesktopStatus": "Running",
      "DesktopType": "ecd.basic.large",
      "GpuCount": 1,
      "ProtocolType": "ASP",
      "Memory": 4096,
      "GpuSpec": "NVIDIA T4",
      "ImageId": "m-4zfb6zj728hhr****",
      "ImageName": "Windows server 2019 Mainland",
      "DirectoryId": "cn-hangzhou+dir-363353****",
      "ManagementFlag": "NoFlag",
      "DataDiskCategory": "cloud_auto",
      "SystemDiskCategory": "cloud_auto",
      "NetworkInterfaceId": "123456",
      "OfficeSiteId": "cn-hangzhou+dir-363353****",
      "DataDiskSize": "80",
      "DesktopGroupId": "dg-2i8qxpv6t1a03****",
      "DesktopId": "ecd-gx2x1dhsmucyy****",
      "OfficeSiteName": "default",
      "StartTime": "2020-11-06T08:31Z",
      "DirectoryType": "SIMPLE",
      "Cpu": 2,
      "NetworkInterfaceIp": "192.168.XX.XX",
      "ExpiredTime": "2021-12-31T15:59Z",
      "OsType": "Windows",
      "ConnectionStatus": "Disconnected",
      "BundleId": "b-2g65ljy4291vl****",
      "BundleName": "TemplateName",
      "OfficeSiteType": "SIMPLE",
      "HostName": "testName",
      "Disks": [
        {
          "DiskType": "SYSTEM",
          "DiskId": "d-jedbpr4sl9l37****",
          "DiskSize": 80,
          "PerformanceLevel": "PL0",
          "DiskCategory": "cloud_auto"
        }
      ],
      "Tags": [
        {
          "Key": "TestKey",
          "Value": "TestValue"
        }
      ],
      "Sessions": [
        {
          "EndUserId": "29615820929547****",
          "EstablishmentTime": "2021-03-07T08:23Z",
          "ExternalUserName": "Testname"
        }
      ],
      "EndUserIds": [
        "alice"
      ],
      "DowngradeQuota": 3,
      "DowngradedTimes": 0,
      "GpuCategory": 0,
      "GpuDriverVersion": "471.68",
      "ZoneType": "AvailabilityZone",
      "FotaUpdate": {
        "CurrentAppVersion": "0.0.0-D-20220102.000000",
        "NewAppVersion": "0.0.0-R-20220307.190736",
        "ReleaseNote": "Test upgrade package 03-07",
        "Size": 108815097,
        "ReleaseNoteEn": "What's new",
        "ReleaseNoteJp": "リリースノート"
      },
      "Progress": "100%",
      "VolumeEncryptionEnabled": false,
      "VolumeEncryptionKey": "08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****",
      "OfficeSiteVpcType": "basic",
      "Platform": "Ubuntu",
      "SessionType": "SINGLE_SESSION",
      "ManagementFlags": [
        "[\"NoFlag\"]"
      ],
      "SnapshotPolicyId": "sp-gi007jgyc3kce****",
      "SnapshotPolicyName": "testSnapshotName",
      "BindAmount": 2,
      "PolicyGroupIdList": [
        "pg-dasffjkdf*****"
      ],
      "PolicyGroupNameList": [
        "TestPolicy01"
      ],
      "HibernationOptionsConfigured": true,
      "SupportHibernation": true,
      "HibernationBeta": true,
      "ResourceGroups": [
        {
          "Name": "ResourceGroup01",
          "Id": "rg-4hsvzbbmqdzu3s****"
        }
      ],
      "StandardStartTime": "2025-01-27T02:20:10Z",
      "OsUpdate": {
        "CheckId": "ck-8f2a1b****",
        "PackageCount": 3,
        "Packages": [
          {
            "Kb": "KB5032190",
            "Title": "2021-05 Servicing Stack Update for Windows Server 2019 for x64-based Systems (KB5003243)",
            "Description": "newDescription"
          }
        ]
      },
      "IsLdap": false,
      "DomainType": "AD",
      "SerialNumber": "96c530bc-6095-4014-8bbc-d461b8ac****",
      "AccountType": "SIMPLE",
      "EntraDomainName": "contoso.onmicrosoft.com",
      "EnvType": "Private",
      "EnvId": "adifa****",
      "AgentProviderList": [
        "Wuying"
      ],
      "SubnetId": "vsw-dgea1*****"
    }
  ],
  "PageNumber": 1,
  "PageSize": 10
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.