Help Center/ Workspace/ API Reference/ Workspace APIs/ Report Statistics/ Querying Desktops That Are Not Used in a Specified Period

Updated on 2026-02-10 GMT+08:00

View PDF

Querying Desktops That Are Not Used in a Specified Period

Function

Queries desktops that are idle in a specified period. This API has been discarded and is not recommended. You are advised to use the APIs for querying desktop usage statistics and querying user usage statistics.

Debugging

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

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
workspace:statistics:getUnused	Read	-	-	-	-

URI

GET /v2/{project_id}/desktops/statistics/unused

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
offset	No	Integer	Start position of the data record to be returned. This parameter is used for pagination query. The value ranges from 0 to 2000. The default value is 0.
limit	No	Integer	Number of information items to be returned in the query result. This parameter is used for pagination query. The value ranges from 0 to 2000. The default value is 1000.
start_time	No	String	Start time: The value consists of a date and time in UTC format. The format is yyyy-MM-ddTHH:mm:ss.SSSZ. If this parameter is not specified, unused desktops from the current day to the previous day are queried.
end_time	No	String	End time: The value consists of a date and time in UTC format. The format is yyyy-MM-ddTHH:mm:ss.SSSZ. If this parameter is not specified, unused desktops from the current day to the previous day are queried.

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
unused_desktops	Array of UnusedDesktopInfo objects	Desktops that are not used in a specified period.
total_count	Integer	Total number.

**Table 4** UnusedDesktopInfo
Parameter	Type	Description
desktop_id	String	Desktop ID.
compute_name	String	Desktop name.
create_time	String	Time when a desktop is created.
disconnect_time	String	Last disconnection time.

Status code: default

**Table 5** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.
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

GET /v2/13d4944fcfc7448893f50d81a6a2edd3/desktops/statistics/unused

Example Responses

Status code: 200

Response to the request for querying desktops that are not used in a specified period.

{
  "unused_desktops" : [ {
    "desktop_id" : "e0367f84-1d64-498e-9b92-093002ac3ce8",
    "compute_name" : "ZYZ08",
    "create_time" : "2022-08-08T02:34:05.202Z",
    "disconnect_time" : "2022-08-08T02:39:00.000Z"
  }, {
    "desktop_id" : "b8eb2ac0-4540-4409-857f-df5e2de07546",
    "compute_name" : "wangyan8301",
    "create_time" : "2022-08-08T02:34:05.202Z",
    "disconnect_time" : "2022-08-08T02:39:00.000Z"
  } ],
  "total_count" : 2
}