Help Center/ Cloud Eye/ API Reference/ API V2/ Graphs/ Creating, Copying, or Batch Creating Graphs on a Dashboard

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

View PDF

Creating, Copying, or Batch Creating Graphs on a Dashboard

Function

This API is used to create, copy, or batch create 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:create	Write	-	ces:namespace	-	-

URI

POST /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

Request Parameters

**Table 2** 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

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
[items]	No	Array of BaseWidgetInfo objects	Definition Graph information. Constraints N/A

**Table 4** BaseWidgetInfo
Parameter	Mandatory	Type	Description
group_id	No	String	Definition Graph group ID. Constraints N/A 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. Default Value N/A
metrics	Yes	Array of WidgetMetric objects	Definition Metric list. Constraints Up to 200 metrics may be included, with at least one required.
title	Yes	String	Definition Graph name. Constraints N/A Range The value allows 1 to 128 characters, and can contain digits, letters (including Latin letters), and the following special characters: "≤<>&%_:/;'? +,~()º[. - Default Value N/A
threshold	No	Double	Definition Threshold of metrics on the graph. Constraints N/A Range 0 to 1.7976931348623157e+308 Default Value N/A
threshold_enabled	Yes	Boolean	Definition Whether to display the threshold. Constraints N/A Range true: display false: not display Default Value N/A
view	Yes	String	Definition Graph type. Constraints N/A Range bar: horizontal bar chart line: line chart bar_chart: bar chart table: table circular_bar: radial bar chart area_chart: area chart Default Value N/A
metric_display_mode	Yes	String	Definition Metric display type. Constraints N/A Range single: single-metric multiple: multi-metric Default Value N/A
properties	No	properties object	Definition Additional information. Constraints N/A
location	Yes	location object	Definition Graph coordinates. Constraints N/A
unit	No	String	Definition Unit. Constraints N/A Range [0,32] Default Value N/A

**Table 5** WidgetMetric
Parameter	Mandatory	Type	Description
namespace	Yes	String	Definition Namespace of a service. For details about the namespace of each service, see Namespaces. Constraints N/A 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 (_). It must contain 3 to 32 characters. Default Value N/A
dimensions	Yes	DimensionInfo object	Description Dimension list. Constraints N/A
metric_name	Yes	String	Definition Multiple metric names. Constraints N/A Range The value can contain 1 to 1,080 characters. Multiple metric names are separated by commas (,). Default Value N/A
alias	No	Array of strings	Definition Metric aliases of the graph. Constraints This parameter can be transferred only when the resource type is set to Specified resources.
extra_info	No	ExtraInfo object	Definition Metric information. Constraints N/A
rollup_enable	No	Boolean	Definition Whether to enable aggregation. Constraints If rollup_enable is enabled, rollup_filter and rollup_dimension are mandatory. Range true: enabled false: disabled Default Value false
rollup_filter	No	String	Definition Aggregation rule. Constraints If rollup_enable is enabled, rollup_filter and rollup_dimension are mandatory. Range last: latest value max: maximum value min: minimum value average sum Default Value N/A
rollup_dimension	No	String	Definition Aggregation dimension. Constraints N/A Range 1 to 32 characters Default Value N/A
last_week_compare_enable	No	Boolean	Definition Whether to display comparison data (same period last week). Constraints N/A Range true: display false: not display Default Value N/A
yesterday_compare_enable	No	Boolean	Definition Whether to display comparison data (same period yesterday). Constraints N/A Range true: display false: not display Default Value N/A
metric_dimension	No	String	Definition Dimension name. For details about the dimensions supported by each service, see Service Dimension Names. The value must start with a letter and can only contain digits, letters, underscores (_), and hyphens (-). Multiple dimensions are separated by commas (,). Each dimension allows 32 characters. 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. Constraints N/A Range 1 to 131 characters Default Value N/A
top_num	No	Integer	Definition Number of displayed data records. Constraints N/A Range 1 to 200 Default Value N/A
unit	No	String	Definition Unit. Constraints N/A Range [0,32] Default Value N/A
order	No	String	Definition Sorting field. Constraints N/A Range asc: ascending desc: descending Default Value N/A
topn_metric_name	No	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. Constraints N/A Range 1 to 96 characters Default Value N/A

**Table 6** DimensionInfo
Parameter	Mandatory	Type	Description
name	Yes	String	Description Dimension name. Constraints N/A 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 value can contain 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. Default Value N/A
filter_type	Yes	String	Description Resource type. Constraints N/A Range all_instances: all resources specific_instances: specified resources Default Value N/A
values	No	Array of strings	Description Dimension value list. Constraints N/A

**Table 7** ExtraInfo
Parameter	Mandatory	Type	Description
origin_metric_name	Yes	String	Definition Metric name. Constraints N/A Range 1 to 4,096 characters Default Value N/A
metric_prefix	No	String	Definition Metric name prefix. Constraints N/A Range 1 to 4,096 characters Default Value N/A
metric_type	No	String	Definition Metric type. Constraints N/A Range 1 to 32 characters Default Value N/A
custom_proc_name	No	String	Definition Custom process name. Constraints N/A Range 1 to 250 characters Default Value N/A

**Table 8** properties
Parameter	Mandatory	Type	Description
filter	No	String	Definition Aggregation type. Constraints This parameter is not available for line charts. Range The value can only be TopN. Default Value N/A
topN	No	Integer	Definition Top N values. In a line chart, this parameter indicates the number of time series data records that are randomly displayed. Constraints N/A Range 1 to 2147483647 Default Value 100
order	No	String	Definition Sorting field. Constraints This parameter is not available for line charts. Range asc: ascending desc: descending Default Value N/A
description	No	String	Definition Description of the graph. Constraints N/A Range 0 to 200 Default Value N/A
last_week_compare_enable	No	Boolean	Definition Whether to display comparison data (same period last week). Constraints N/A Range true: display false: not display Default Value N/A
yesterday_compare_enable	No	Boolean	Definition Whether to display comparison data (same period yesterday). Constraints N/A Range true: display false: not display Default Value N/A
legend_location	No	String	Definition Legend location. Constraints This parameter is not available for tables. 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. Default Value N/A
legend_values	No	Array of strings	Definition List of statistical values to be displayed in the legend for the current time series. Constraints This parameter is not available for tables. For horizontal bar charts and vertical bar charts, only last can be selected for this parameter.
thresholds	No	Array of ThresholdInfo objects	Definition Threshold line configured for the graph. Constraints N/A
is_all_compare_enable	No	Boolean	Definition Whether to enable PoP comparison. Constraints N/A Range true: enable false: disable Default Value N/A

**Table 9** ThresholdInfo
Parameter	Mandatory	Type	Description
threshold	Yes	Number	Definition Threshold of the threshold line configured for the graph. Constraints N/A Range The value ranges from 0 to 2147483647. Default Value N/A
threshold_color	Yes	String	Definition Color of the threshold line for the graph. Constraints N/A Range "#B50E65": purple "#F23030": red "#FF8800": orange "#F2E70C": yellow Default Value N/A

**Table 10** location
Parameter	Mandatory	Type	Description
top	Yes	Integer	Definition Grids between the graph and the top of the dashboard. Constraints N/A Range The value ranges from 0 to 2147483647. Default Value N/A
left	Yes	Integer	Definition Grids between the graph and the left side of the dashboard. Constraints N/A Range 0 to 9 Default Value N/A
width	Yes	Integer	Definition Graph width. Constraints N/A Range 3 to 12 Default Value N/A
height	Yes	Integer	Definition Graph height. Constraints N/A Range The value ranges from 3 to 2147483647. Default Value N/A

Response Parameters

Status code: 200

**Table 11** Response body parameters
Parameter	Type	Description
widget_ids	Array of strings	Definition Response body for creating graphs in batches.

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

[ {
  "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" : "%"
} ]

Example Responses

Status code: 200

{
  "widget_ids" : [ "wgx234567890123456789012" ]
}

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.