Dimension Value TopN Query Interface
Updated at：2025-11-03
API description
This API retrieves the TopN dimension values for a specified metric under certain dimensions associated with a cloud product instance.
Request structure
- method：POST
- Request URL: /csm/api/v2/dimensions/top
Request parameters
| Name | Types | Description | Required or not | Parameter location |
|---|---|---|---|---|
| userId | String | User ID | Yes | Body |
| scope | String | Cloud product identifier. For values, please refer to [Cloud Product Identifier List](BCM/Cloud Product Monitor List/Cloud Product Monitor Object Type List.md) | Yes | Body |
| region | String | Region identifier. For values, please refer to [Region List](BCM/API Reference/Service domain.md) | Yes | Body |
| metricName | String | Monitor Metric | Yes | Body |
| statistics | String | Statistic method type. Optional values: average, maximum, minimum, sum, sampleCount. | Yes | Body |
| dimensions | Map<String, String> | Instance dimensions and metric dimensions, instance dimensions: Instance ID or parent instance ID (required); metric dimensions: Dimensions carried by the monitoring metric (optional) | Yes | Body |
| labels | Set<String> | Metric dimensions to be sorted | Yes | Body |
| startTime | String | Monitor data start time, refer to [Date and Time](BCM/API Reference/General Description.md), in UTC format | Yes | Body |
| endTime | String | Monitor data end time, refer to [Date and Time](BCM/API Reference/General Description.md), expressed in UTC date | Yes | Body |
| order | String | Sorting method, optional values top (descending), bottom (ascending), default top | No | Body |
| topNum | int | Number of topNum items retained after sorting, default: 10, maximum: 1000 | No | Body |
Parameter explanation
- For concepts like Scope, Metric, Statistic, and Dimension, refer to [Core Concepts](BCM/Product Description/Core concepts.md).
Response parameters
| Name | Types | Description |
|---|---|---|
| requestId | String | Request identifier ID |
| topDatas | List<TopData> | Sorted list of dimension values |
TopData
| Name | Types | Description |
|---|---|---|
| order | int | Ranking, starting from 1 |
| dimensions | List<Dimension> | Dimension Information |
Dimension
| Name | Types | Description |
|---|---|---|
| name | String | Dimension name |
| value | String | Dimension value |
Request example
JSON
1{
2 "userId": "0b8ed5********************8fb898",
3 "scope": "BCE_NAT",
4 "region": "bj",
5 "metricName": "ConnNumber",
6 "statistics": "average",
7 "startTime": "2024-04-27T07:10:01Z",
8 "endTime": "2024-04-27T07:20:01Z",
9 "dimensions": {
10 "NatId": "nat-b51******70"
11 },
12 "labels": [
13 "FixIp"
14 ],
15 "topNum": 2,
16 "order": "top"
17}Response example
JSON
1{
2 "requestId": "9083c1ec306b4fceb56190b71ac02a81",
3 "topDatas": [
4 {
5 "order": 1,
6 "dimensions": [
7 {
8 "name": "FixIp",
9 "value": "172.16.1.4"
10 }
11 ]
12 },
13 {
14 "order": 2,
15 "dimensions": [
16 {
17 "name": "FixIp",
18 "value": "172.16.1.5"
19 }
20 ]
21 }
22 ]
23}