Help Center/ Cloud Eye/ API Reference/ API/ Cloud Resource Monitoring/ Monitoring Data Management/ Querying Monitoring Data
Updated on 2026-06-11 GMT+08:00
View PDF
Share

Querying Monitoring Data

Function

This API is used to query the monitoring metric data at a specified granularity in a specified period of time.

Constraints

Notes:

  • dim can be obtained from the response body by calling the API for listing metrics.

  • OBS metric data can be queried only when the related OBS APIs are called.

  • For EVS metric data under the disk_name dimension, the returned value can be in either of the following formats:

    • Server ID-Drive letter, for example, 6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d-vda (vda is the drive letter).

    • Cloud server ID-volume-Volume ID, for example, 6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d-volume-31f45764-38b3-44ad-aaca-4015c83371e6.

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:metricData:get

    Read

    -

    -

    ces:metricData:list

    -

URI

GET /V1.0/{project_id}/metric-data

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
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

namespace

Yes

String

Definition

Service namespace, for example, the namespace of ECS is SYS.ECS .

For details about service namespaces, see Services Interconnected with Cloud Eye.

Constraints

N/A

Range

The value is in the format of service.item, where service and item are separated by a period (.).

service and item each must start with a letter. They can contain letters, digits, and underscores (_) and allow 3 to 32 characters.

Default Value

N/A

metric_name

Yes

String

Definition

Metric name of the resource, for example, cpu_util of the ECS monitoring metric.

For details about the metric names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye.

Constraints

N/A

Range

The value must start with a letter. It can contain letters, digits, underscores (_), and hyphens (-) and allows 1 to 96 characters.

Default Value

N/A

dim.0

Yes

String

Definition

First-level dimension of a metric. A maximum of four dimensions are supported. The dimension format is dim.{i}=key,value. A key,value example is instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d .

For details about the dimension names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye.

Constraints

N/A

Range

Format: dim.0=key,value. key and value are separated by a comma (,).

key must start with a letter. It can contain letters, digits, underscores (), and hyphens (-) and allows 1 to 32 characters. value can contain letters, digits, underscores (), hyphens (-), periods (.), slashes (/), number signs (#), and parentheses. It cannot start with a hyphen (-) but can start with an asterisk (*) or other allowed characters. It allows 1 to 256 characters.

Default Value

N/A

dim.1

No

String

Definition

Second-level dimension of a metric. A maximum of four dimensions are supported. The dimension format is dim.{i}=key,value. A key,value example is instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d .

For details about the dimension names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye.

Constraints

N/A

Range

Format: dim.1=key,value. key and value are separated by a comma (,).

key must start with a letter. It can contain letters, digits, underscores (), and hyphens (-) and allows 1 to 32 characters. value can contain letters, digits, underscores (), hyphens (-), periods (.), slashes (/), number signs (#), and parentheses. It cannot start with a hyphen (-) but can start with an asterisk (*) or other allowed characters. It allows 1 to 256 characters.

Default Value

N/A

dim.2

No

String

Definition

Third-level dimension of a metric. A maximum of four dimensions are supported. The dimension format is dim.{i}=key,value. A key,value example is instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d .

For details about the dimension names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye.

Constraints

N/A

Range

Format: dim.2=key,value. key and value are separated by a comma (,).

key must start with a letter. It can contain letters, digits, underscores (), and hyphens (-) and allows 1 to 32 characters. value can contain letters, digits, underscores (), hyphens (-), periods (.), slashes (/), number signs (#), and parentheses. It cannot start with a hyphen (-) but can start with an asterisk (*) or other allowed characters. It allows 1 to 256 characters.

Default Value

N/A

dim.3

No

String

Definition

Fourth-level dimension of a metric. A maximum of four dimensions are supported. The dimension format is dim.{i}=key,value. A key,value example is instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d .

For details about the dimension names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye.

Constraints

N/A

Range

Format: dim.3=key,value. key and value are separated by a comma (,).

key must start with a letter. It can contain letters, digits, underscores (), and hyphens (-) and allows 1 to 32 characters. value can contain letters, digits, underscores (), hyphens (-), periods (.), slashes (/), number signs (#), and parentheses. It cannot start with a hyphen (-) but can start with an asterisk (*) or other allowed characters. It allows 1 to 256 characters.

Default Value

N/A

filter

Yes

String

Definition

Aggregation method.

Constraints

N/A

Range

The value can be:

  • average

  • variance

  • min: minimum value.

  • max: maximum value.

  • sum

Default Value

N/A

period

Yes

Integer

Definition

Aggregation granularity of monitoring data. For details about the aggregation, see What Is Aggregation?

Constraints

N/A

Range

The value can be:

  • 1: real-time data of monitored resources.

  • 60: Data is aggregated every one minute (one data point per minute).

  • 300: Data is aggregated every 5 minutes (one data point every 5 minutes).

  • 1200: Data is aggregated every 20 minutes (one data point every 20 minutes).

  • 3600: Data is aggregated every hour (one data point per hour).

  • 14400: Data is aggregated every 4 hours (one data point every four hours).

  • 86400: Data is aggregated every one day (one data point per day).

Default Value

N/A

from

Yes

Long

Definition

Start time of the query. The value is a UNIX timestamp in milliseconds. You are advised to set from to at least one period earlier than the current time. This is because Cloud Eye aggregates raw data generated within an aggregation period to the start time of the period. Therefore, if from and to are within an aggregation period, the query result will be empty due to the aggregation failure. Take the 5-minute period as an example. If the current time is 10:35, the raw data generated between 10:30 and 10:35 will be aggregated to 10:30. Therefore, in this example, if period is 5 minutes, from should be 10:30 or earlier. Cloud Eye rounds up the value of from based on the selected aggregation granularity. Example: 1607146998177

Constraints

N/A

Range

The millisecond-level timestamp range is [1111111111111,9999999999999].

Default Value

N/A

to

Yes

Long

Definition

End time of the query. The value is a UNIX timestamp in milliseconds.

Constraints

The value of from must be earlier than that of to.

Range

The millisecond-level timestamp range is [1111111111111,9999999999999].

Default Value

N/A

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

Content-Type

No

String

Definition

MIME type of the request body.

Constraints

N/A

Range

1 to 64 characters

Default Value

Default value application/json; charset=UTF-8 is recommended. For APIs used to upload objects or images, the MIME type varies with the flow type.

X-Auth-Token

No

String

Definition

User token.

Constraints

N/A

Range

1 to 16,384 characters

Default Value

N/A

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

datapoints

Array of Datapoint objects

Definition

Metric data list. Since Cloud Eye rounds up from based on the level of granularity for data query, datapoints may contain more data points than expected.

metric_name

String

Definition

Metric name, for example, an ECS metric is cpu_util.

Range

N/A
Table 5 Datapoint

Parameter

Type

Description

max

Double

Definition

Maximum value of metric data within an aggregation period.

Range

N/A

min

Double

Definition

Minimum value of metric data within an aggregation period.

Range

N/A

average

Double

Definition

Average value of metric data within an aggregation period.

Range

N/A

sum

Double

Definition

Sum of metric data within an aggregation period.

Range

N/A

variance

Double

Definition

Variance value of metric data within an aggregation period.

Range

N/A

timestamp

Long

Definition

Time when the metric was collected. It is a UNIX timestamp in millisecond.

Range

N/A

unit

String

Definition

Metric unit.

Range

N/A

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

-

String

Request error.

Status code: 401

Table 7 Response body parameters

Parameter

Type

Description

-

String

The authentication information is not provided or is incorrect.

Status code: 403

Table 8 Response body parameters

Parameter

Type

Description

-

String

Access to the requested page is forbidden.

Status code: 408

Table 9 Response body parameters

Parameter

Type

Description

-

String

The request timed out.

Status code: 429

Table 10 Response body parameters

Parameter

Type

Description

-

String

Too many requests.

Status code: 500

Table 11 Response body parameters

Parameter

Type

Description

-

String

Failed to complete the request because of an internal service error.

Status code: 503

Table 12 Response body parameters

Parameter

Type

Description

-

String

The system is currently unavailable.

Example Requests

/V1.0/{project_id}/metric-data?namespace=SYS.ECS&metric_name=cpu_util&dim.0=instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d&from=1442347449274&to=1442390649274&period=1200&filter=min

Example Responses

Status code: 200

OK

{
  "datapoints" : [ {
    "average" : 0,
    "timestamp" : 1442341200000,
    "unit" : "Count"
  } ],
  "metric_name" : "cpu_util"
}

Status Codes

Status Code

Description

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

408

Request Timeout

429

Too Many Requests

500

Internal Server Error

503

Service Unavailable

Error Codes

See Error Codes.