Custom Monitor - Query Data API

Last Updated：2025-11-14

API description

Retrieve time-series data for one or more statistics pertaining to specified custom monitor metrics.

API restriction

The number of DataPoints returned in a single response cannot exceed 1,440.

Request structure

Method: POST
Request URL: /csm/api/v1/userId/{userId}/custom/namespaces/{namespace}/metrics/{metricName}/data

Parameter list

URL parameter

Name	Types	Description	Required or not
userId	String	Tenant ID	Yes
namespace	String	Scope	Yes
metricName	String	Monitor Metric name	Yes

RequestBody

Name	Types	Description	Required or not
statistics	String, optional values: average, maximum, minimum, sum, sampleCount	Statistic Method Type	Yes
dimensions	List<String>, consisting ofdimensionName:dimensionValue. When a Metric has multiple Dimensions, connect them with semicolons, e.g., dimensionName:dimensionValue;dimensionName:dimensionValue. Only one dimension value can be specified for the same dimension	Dimension list	Yes
startTime	String, refer to Date and Time, expressed in UTC date	Query start time	Yes
endTime	String, refer to Date and Time, expressed in UTC date	Query end time	Yes
cycle	Integer, unit: second (s)	Statistical Period	Yes

Parameter explanation

For concepts like Namespace, Metric, Statistic, and Dimensions refer to [Core Concepts](BCM/Product Description/Core concepts.md).

Response parameters

Name	Types	Description
requestId	String	Request identifier
code	String	Return code
message	String	Error message
dataPoints	List（DataPoint）	Monitor Metric
dimensions	List（Dimensions）	Dimension Combination

DataPoint

Name	Types	Description
average	double	Average of Metrics within the statistical period
sum	double	Sum of Metrics within the statistical period
minimum	double	Minimum value of Metrics within the statistical period
maximum	double	Maximum value of Metrics within the counting cycle
sampleCount	Integer	Number of DataPoints for the Metric within the statistical period
timestamp	String, refer to [Date and Time](BCM/API Reference/General Description.md#Date and time regulations), expressed in UTC date	Time corresponding to the statistical period of Metric

Dimensions

Name	Types	Description
name	String	Dimension name
value	String	Dimension value

Request example

POST  /csm/api/v1/userId/useer1/custom/namespaces/namespace1/metrics/metricName1/data  HTTP/1.1  
Host:bcm.cnhzpro.agilecloud.com:80  

{
    "startTime":"2020-12-31T08:00:00Z",
    "endTime":"2020-12-31T08:02:00Z",
    "dimensions":[
        "dimension1:myMachine;dimension2:myService"
    ],
    "statistics":"average",
    "cycle":60
}

Response example

Successful response example

When querying data, ensure the statistics parameter is provided. Its value determines the attributes assigned to each DataPoint in the response.

When statistics=average, the response result example is as follows:

HTTP/1.1 200 OK
x-bce-request-id: dwegvad4-dwea-4d3dsa-8ew2-4b7263fs1ecd
Content-Type: application/json;charset=UTF-8
[
    {
        "dataPoints": [
            {
                "average": 2.24,
                "timestamp": "1609387200"
            },
            {
                "average": 0.22,
                "timestamp": "1609387260"
            },
            {
                "average": 0.19,
                "timestamp": "1609387320"
            }
        ],
        "dimensions":[
            {
                "name": "dimension1",
                "value": "myMachine"
            },
            {
                 "name": "dimension2",
                    "value": "myService"
            }
        ]
    }
]

Unsuccessful response example

Case 1: No data found. No monitoring data was identified for the specified user, scope, metric, and dimension within the requested timeframe.

When this occurs, the corresponding time point will be returned, but without monitor data

HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
[
    {
        "dataPoints": [
            {
                "timestamp": "1609387200"
            },
            {
                "timestamp": "1609387260"
            },
            {
                "timestamp": "1609387320"
            }
        ],
        "dimensions":[
            {
                "name": "dimension1",
                "value": "myMachine"
            },
            {
                 "name": "dimension2",
                    "value": "myService"
            }
        ]
    }
]

Case 2: Incorrect parameters. The given example showcases the statistics parameter being outside the permissible range of values.

HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
    "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
    "code": "ParameterValueException",
    "message": "The request param value: max is misMatch."
}

The example below demonstrates an incorrect format for Dimension parameter values.

HTTP/1.1 200 OK
x-bce-request-id: dd00bad4-d22a-4d1c-8f12-4b513f0b91ec
Content-Type: application/json;charset=UTF-8
{
    "requestId": "dd00bad4-d22a-4d1c-8f12-4b513f0b91ec",
    "code": "ParamValueNotInScopeException",
    "message": "The request param dimension value mismatch."
}

Custom Monitor - Push Data API

Custom Monitor Interface

百度智能云

Cloud Monitor