Help Center/ Workspace/ API Reference/ Workspace APIs/ Desktop/ Querying Desktop Monitoring Data
Updated on 2025-07-14 GMT+08:00

Querying Desktop Monitoring Data

Function

Queries data (such as the CPU usage, memory usage, and period when a user is online) of a desktop in a time range (from 1 hour to 30 days). The data can be retained for up to 180 days.

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-monitor/{desktop_id}

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID.

desktop_id

Yes

String

Desktop ID.

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

start_time

Yes

String

Monitoring start time: The value is in UTC format, for example, 2021-05-11T11:45:42Z.

end_time

Yes

String

Monitoring end time: The value is in UTC format, for example, 2021-05-11T11:45:42Z.

metric_name

No

String

Monitoring metrics, for example, cpu_util. For details, see the following table. If metric_name is left blank, batch query will be performed.| Metric | Metric Name | Monitored Object | Monitoring Period || ------------------------------------- | ----------------- | ------------ | -------- || cpu_util | CPU usage | Workspace | 5 min || mem_util | Memory usage | Workspace | 5 min || disk_util_inband | Disk usage | Workspace | 5 min || disk_read_bytes_rate | Disk read bandwidth | Workspace | 5 min || disk_write_bytes_rate | Disk write bandwidth | Workspace | 5 min || disk_read_requests_rate | Disk read IOPS | Workspace | 5 min || disk_write_requests_rate | Disk write IOPS | Workspace | 5 min || network_incoming_bytes_rate_inband | Inband incoming rate | Workspace | 5 min || network_outgoing_bytes_rate_inband | Inband outgoing rate | Workspace | 5 min || network_incoming_bytes_aggregate_rate | Outband incoming rate | Workspace | 5 min || network_outgoing_bytes_aggregate_rate | Outband outgoing rate | Workspace | 5 min || network_vm_connections | Number of network connections | Workspace | 5 min || cpu_credit_usage | CPU credit usage | Workspace | 5 min || cpu_credit_balance | Accumulated CPU credits | Workspace | 5 min || cpu_surplus_credit_balance | Accumulated CPU surplus credits | Workspace | 5 min || cpu_surplus_credit_charged | CPU surplus credits charged | Workspace | 5 min || user_online_info | User online information | Workspace | - |

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 that is used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Content-Type

No

String

MIME type of the request body.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

user_online_info

Array of MonitorUserOnlineInfo objects

Online information.

online_status

Integer

Desktop login status. If the online information is empty, the login status can be 0 (not logged in to), 1 (logging in), or 2 (logged in to).

cpu_info

Array of Datapoints objects

CPU usage.

memory_info

Array of Datapoints objects

Memory usage.

disk_util_inband

Array of Datapoints objects

Disk usage.

disk_read_bytes_rate

Array of Datapoints objects

Disk read bandwidth.

disk_write_bytes_rate

Array of Datapoints objects

Disk write bandwidth.

disk_read_requests_rate

Array of Datapoints objects

Disk read IOPS.

disk_write_requests_rate

Array of Datapoints objects

Disk write IOPS.

network_incoming_bytes_rate_inband

Array of Datapoints objects

Inband incoming rate.

network_outgoing_bytes_rate_inband

Array of Datapoints objects

Inband outgoing rate.

network_incoming_bytes_aggregate_rate

Array of Datapoints objects

Outband incoming rate.

network_outgoing_bytes_aggregate_rate

Array of Datapoints objects

Outband outgoing rate.

network_vm_connections

Array of Datapoints objects

Number of network connections.

Table 5 MonitorUserOnlineInfo

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.

connection_setup_time

String

Connection setup time.

connection_end_time

String

Connection end time.

Table 6 Datapoints

Parameter

Type

Description

average

Double

Average value.

timestamp

Long

Timestamp.

Status code: default

Table 7 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/e3662787cb914315b85fd83aa53b93b1/desktop-monitor/a130ab3a-72bf-4b71-baa9-af4987c8e338?start_time=2021-10-11T06%3A56%3A56Z&end_time=2021-10-11T07%3A56%3A56Z
  • /v2/e3662787cb914315b85fd83aa53b93b1/desktop-monitor/a130ab3a-72bf-4b71-baa9-af4987c8e338?start_time=2021-10-11T06%3A56%3A56Z&end_time=2021-10-11T07%3A56%3A56Z&metric_name=cpu_util

Example Responses

Status code: 200

Response to the request for exporting desktop monitoring data.

{
  "cpu_info" : [ {
    "average" : 0.4832775919732441,
    "timestamp" : 1618810632000
  }, {
    "average" : 0.4832775919732441,
    "timestamp" : 1618810931000
  }, {
    "average" : 0.5018382352941176,
    "timestamp" : 1618811203000
  }, {
    "average" : 0.4830508474576271,
    "timestamp" : 1618812396000
  } ]
}

Status Codes

Status Code

Description

200

Response to the request for exporting desktop monitoring data.

default

Default error response.

Error Codes

See Error Codes.