Help Center/ Cloud Eye/ API Reference/ API V2/ Graphs/ Querying Graphs Added to a Dashboard

Updated on 2025-10-30 GMT+08:00

View PDF

Querying Graphs Added to a Dashboard

Function

This API is used to query graphs on a dashboard.

Constraints

This API is not supported in the following regions: CN East-Qingdao, LA-Mexico City1, TR-Istanbul, AP-Jakarta, ME-Riyadh, and AP-Manila.

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
ces:widgets:list	List	-	-	-	-

URI

GET /v2/{project_id}/dashboards/{dashboard_id}/widgets

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. It is used to specify the project that an asset belongs to. You can query the assets of a project by project ID. You can obtain the project ID from the API or console. For details, see Obtaining a Project ID. Constraints N/A Range 1 to 64 characters Default Value N/A
dashboard_id	Yes	String	Definition Dashboard ID. Constraints N/A Range The value starts with db and is followed by 22 characters of letters, digits, or a combination of both. The total length is 24 characters. Default Value N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
group_id	No	String	ID of the group that the graph belongs to.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	No	String	Definition MIME type of the request body. Constraints: None Value range: The value can contain 1 to 64 characters. Default value: The default type is application/json; charset=UTF-8.
X-Auth-Token	No	String	Definition User token. Constraints: None Value range: The value can contain 1 to 16,384 characters. Default value: None

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
widgets	Array of WidgetInfoWithId objects	Graph list.

**Table 5** WidgetInfoWithId
Parameter	Type	Description
widget_id	String	Definition Graph ID. Range The value must start with wg and is followed by 22 characters of letters, digits, or a combination of both. The total length is 24 characters.
group_id	String	Definition Graph group ID. Range The value must start with dg and is followed by 22 characters of letters, digits, or a combination of both. The total length is 24 characters. The value can also be default (no grouping).
metrics	Array of WidgetMetricResp objects	Definition Metric list.
title	String	Definition Graph name. Range The value allows 1 to 128 characters, and can contain digits, letters (including Latin letters), and the following special characters: "≤<>&%_:/;'? +,~()º[. -
threshold	Double	Definition Threshold of metrics on the graph. Range 0 to 1.7976931348623157e+308
threshold_enabled	Boolean	Definition Whether to display the threshold. Range true: display false: not display
view	String	Definition Graph type. Range bar: horizontal bar chart line: line chart bar_chart: bar chart table: table circular_bar: radial bar chart area_chart: area chart
metric_display_mode	String	Definition Metric display type. Range single: single-metric multiple: multi-metric
properties	properties object	Definition Additional information. Range N/A
location	location object	Definition Graph coordinates. Range N/A
unit	String	Definition Unit. Range [0,32]
create_time	Long	Definition Dashboard creation time. Range 1111111111111 to 9999999999999

**Table 6** WidgetMetricResp
Parameter	Type	Description
namespace	String	Definition Namespace of a service. For details about the namespace of each service, see Namespaces. Range The value is in the service.item format. The values of service and item must be a string, starting with a letter and containing only digits (0–9), letters (case-insensitive), and underscores (_). The value must contain 3 to 32 characters.
dimensions	DimensionInfoResp object	Description Dimension list.
metric_name	String	Definition Multiple metric names. Range The value can contain 1 to 1,080 characters. Multiple metric names are separated by commas (,).
alias	Array of strings	Definition Metric aliases of the graph.
extra_info	ExtraInfoResp object	Definition Metric information.
rollup_enable	Boolean	Definition Whether to enable aggregation. Range true: enabled false: disabled
rollup_filter	String	Definition Aggregation rule. Range last: latest value max: maximum value min: minimum value average sum
rollup_dimension	String	Definition Aggregation dimension. Range 1 to 32 characters
last_week_compare_enable	Boolean	Definition Whether to display comparison data (same period last week). Range true: display false: not display
yesterday_compare_enable	Boolean	Definition Whether to display comparison data (same period yesterday). Range true: display false: not display
metric_dimension	String	Definition Dimension name. Multiple dimensions are separated using commas (,). For details about the dimensions supported by each cloud service, see Services Interconnected with Cloud Eye. Range The value must start with a letter. Each dimension allows 1 to 32 characters and can only contain letters, digits, underscores (_), and hyphens (-). Multiple dimensions are separated using commas (,). The value contains 1 to 131 characters. A maximum of four dimensions are supported. Example: instance_id for single-dimension scenarios; instance_id,disk for multi-dimension scenarios.
top_num	Integer	Definition Number of displayed data records. Range 1 to 200
unit	String	Definition Unit. Range [0,32]
order	String	Definition Sorting field. Range asc: ascending desc: descending
topn_metric_name	String	Definition Metric name of a resource. The name must start with a letter and contain only digits, letters, and underscores. The length ranges from 1 to 64 characters. For example, cpu_util of an ECS indicates the CPU usage of the ECS. mongo001_command_ps in DDS indicates the command execution frequency. For details about the metric name of each service, see Service Metric Names. Range 1 to 96 characters

**Table 7** DimensionInfoResp
Parameter	Type	Description
name	String	Description Dimension name. Range Multiple dimensions are separated using commas (,). For details about the dimensions supported by each cloud service, see Services Interconnected with Cloud Eye. The value must start with a letter. Each dimension allows 1 to 32 characters and can only contain letters, digits, underscores (_), and hyphens (-). Multiple dimensions are separated using commas (,). The total length is 1 to 131 characters. A maximum of four dimensions are supported. Example: instance_id for single-dimension scenarios; instance_id,disk for multi-dimension scenarios.
filter_type	String	Description Resource type. Range all_instances: all resources specific_instances: specified resources
values	Array of strings	Description Dimension value list.

**Table 8** ExtraInfoResp
Parameter	Type	Description
origin_metric_name	String	Definition Metric name. Range 1 to 4,096 characters
metric_prefix	String	Definition Metric name prefix. Range 1 to 4,096 characters
metric_type	String	Definition Metric type. Range 1 to 32 characters
custom_proc_name	String	Definition Custom process name. Range 1 to 250 characters

**Table 9** properties
Parameter	Type	Description
filter	String	Definition Aggregation type. Range The value can only be TopN. This parameter is not available for line charts.
topN	Integer	Definition Top N values. In a line chart, this parameter indicates the number of time series data records that are randomly displayed. Range 1 to 2147483647
order	String	Definition Sorting field. Range asc: ascending desc: descending
description	String	Definition Description of the graph. Range [0,200]
last_week_compare_enable	Boolean	Definition Whether to display comparison data (same period last week). Range true: display false: not display
yesterday_compare_enable	Boolean	Definition Whether to display comparison data (same period yesterday). Range true: display false: not display
legend_location	String	Definition Legend location. Range hide: Hide the legend. right: Place the legend on the right of the graph. bottom: Place the legend at the bottom of the graph.
legend_values	Array of strings	Definition List of statistical values to be displayed in the legend for the current time series.
thresholds	Array of ThresholdInfoResp objects	Definition Threshold line configured for the graph.
is_all_compare_enable	Boolean	Definition Whether to enable PoP comparison. Range true: enable false: disable

**Table 10** ThresholdInfoResp
Parameter	Type	Description
threshold	Number	Definition Threshold of the threshold line configured for the graph. Range 0 to 2147483647
threshold_color	String	Definition Color of the threshold line for the graph. Range "#B50E65": purple "#F23030": red "#FF8800": orange "#F2E70C": yellow

**Table 11** location
Parameter	Type	Description
top	Integer	Definition Grids between the graph and the top of the dashboard. Range The value ranges from 0 to 2147483647.
left	Integer	Definition Grids between the graph and the left side of the dashboard. Range 0 to 9
width	Integer	Definition Graph width. Range 3 to 12
height	Integer	Definition Graph height. Range 3 to 2147483647

Status code: 400

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Status codes customized by each cloud service when a request error occurs.
error_msg	String	Request error message.
request_id	String	Request ID.

Status code: 401

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Status codes customized by each cloud service when a request error occurs.
error_msg	String	Request error message.
request_id	String	Request ID.

Status code: 500

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Status codes customized by each cloud service when a request error occurs.
error_msg	String	Request error message.
request_id	String	Request ID.

Example Requests

None

Example Responses

Status code: 200

[ {
  "widget_id" : "wg1234567890123456789012",
  "metrics" : [ {
    "namespace" : "SYS.ECS",
    "dimensions" : {
      "name" : "instance_id",
      "filter_type" : "specific_instances",
      "values" : [ "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" ],
      "metric_name" : "cpu_util",
      "alias" : [ "cpuutilalias" ],
      "extra_info" : {
        "origin_metric_name" : "cpu_util",
        "metric_prefix" : "cpu",
        "metric_type" : "type",
        "custom_proc_name" : "app.sh"
      }
    }
  } ],
  "view" : "bar",
  "metric_display_mode" : "single",
  "threshold" : 0.7,
  "threshold_enabled" : true,
  "title" : "widget_title",
  "properties" : {
    "filter" : "topN",
    "topN" : 100,
    "order" : "desc"
  },
  "location" : {
    "left" : 0,
    "top" : 0,
    "width" : 4,
    "height" : 3
  },
  "unit" : "%",
  "create_time" : 1111111111111
} ]

Status Codes

Status Code	Description
200	OK
400	The server failed to process the request.
401	Token authentication is required.
500	Failed to complete the request because of an internal server error.