QueryHistoryAvgMetricList - Elastic Desktop Service - Alibaba Cloud Documentation Center

Retrieves historical average monitoring metrics for a desktop resource over a specified date range.

Operation description

Request

This API retrieves historical average monitoring metrics for desktop resources that meet specified criteria within a time range.
The DataDate and EndDate parameters specify the time range. If omitted, the query defaults to the previous day.
You can filter results by criteria such as desktop ID, name, and custom numeric ranges.
The response contains the details of each matching desktop resource and its corresponding average values.
Use the PageNum and PageSize pagination parameters to control the number of results returned.
Note: When using the Ranges parameter, ensure that you provide reasonable intervals. Unreasonable intervals can degrade query performance or lead to invalid results.

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

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request syntax

POST  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
MetricName	string	No	The metric to query. Valid values: LOAD_SCORE : Health score GPU_USAGE : GPU usage CPU_TOTAL_USAGE : CPU usage MEMORY_USAGE : Memory usage ROUND_TRIP_TIME : End-to-end latency TOTAL_DISK_USAGE : Disk usage	LOAD_SCORE
DataDate	string	No	The start date of the statistics. The format is `YYYY-MM-DD`. The default value is T-1.	2026-04-01
DesktopId	array	No	The desktop ID list. A maximum of 100 IDs are supported.
	string	No	The ID of the cloud computer.	ecd-2h7u3ymhm33qy****
ResourceRegionId	string	No	The desktop region.	cn-hangzhou
Range	object	No	The list of custom numeric ranges.
Label	string	No	The range label, which is used for the return value.	label-02'
Min	number	No	The minimum value.	0
IncludeMin	boolean	No	Specifies whether to include the minimum value. Default value: true.	true
Max	number	No	The maximum value.	20
IncludeMax	boolean	No	Specifies whether to include the maximum value. Default value: false.	false
SortType	string	No	The sorting method. Valid values: ASC : Ascending DESC : Descending	ASC
PageNum	integer	No	The page number, which must be greater than 0. Default value: 1.	1
PageSize	integer	No	The page size. Valid values: 1 to 200. Default value: 20.	20

Response elements

Element	Type	Description	Example
	object	The response object.
RequestId	string	The request ID.	269BDB16-2CD8-4865-84BD-11C40BC2****
AvgMetricList	array<object>	The list of average metric data.
	array<object>	The average metric data for a single resource.
DesktopId	string	The desktop ID.	ecd-bx9i0nsjd3zmibnzq
DesktopName	string	The desktop name.	C-051
DesktopGroupId	string	The computer pool ID.	dg-bogo95eob5avnis9k
MultiResource	boolean	Whether the desktop is a multi-user shared cloud computer.	true
DesktopStatus	string	The status of the desktop. Valid values: `Stopped`: The desktop is stopped. `Starting`: The desktop is being started. `Rebuilding`: The desktop is being rebuilt. `Running`: The desktop is running. `Stopping`: The desktop is being stopped. `Expired`: The desktop has expired. `Deleted`: The desktop has been deleted. `Pending`: The desktop is in a pending state.	Running
ManagementFlag	string	The management flag.	0
ChargeType	string	The billing method of the desktop. Valid values: `PostPaid`: pay-as-you-go `PrePaid`: subscription Default value: `PostPaid`.	PrePaid
DesktopType	string	The desktop type.	eds.enterprise_office.8c16g
Platform	string	The type of the system image.	Winserver2025
SubPayType	string	The payment type.	monthPackage
AvgValue	number	The aggregated metric value.	20
Cpu	integer	The number of vCPUs.	4
GpuSpec	string	The GPU memory size.	0
Memory	integer	The memory size, in MB.	2048
EndUserIds	array	The IDs of the authorized end users.
	string	The ID of an authorized end user.	testUser
Sessions	array<object>	A list of session details.
	object	The details of a session.
EndUserId	string	The ID of the end user.	testUser
NickName	string	The nickname of the end user.	sz-sygc-07-03
ExternalUserName	string	The external username of the end user.	testUserName
EstablishmentTime	string	The time when the session was created.	2026-04-17T14:51:53Z
RegionId	string	The region ID.	cn-hangzhou
TotalCount	integer	The total number of entries.	20

Examples

Success response

JSON format

{
  "RequestId": "269BDB16-2CD8-4865-84BD-11C40BC2****",
  "AvgMetricList": [
    {
      "DesktopId": "ecd-bx9i0nsjd3zmibnzq",
      "DesktopName": "C-051",
      "DesktopGroupId": "dg-bogo95eob5avnis9k",
      "MultiResource": true,
      "DesktopStatus": "Running",
      "ManagementFlag": "0",
      "ChargeType": "PrePaid",
      "DesktopType": "eds.enterprise_office.8c16g",
      "Platform": "Winserver2025",
      "SubPayType": "monthPackage",
      "AvgValue": 20,
      "Cpu": 4,
      "GpuSpec": "0",
      "Memory": 2048,
      "EndUserIds": [
        "testUser"
      ],
      "Sessions": [
        {
          "EndUserId": "testUser",
          "NickName": "sz-sygc-07-03",
          "ExternalUserName": "testUserName",
          "EstablishmentTime": "2026-04-17T14:51:53Z"
        }
      ],
      "RegionId": "cn-hangzhou"
    }
  ],
  "TotalCount": 20
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.