Skip to main content

Query Metrics

Queries the metrics of a cluster.

POST
/v1/clusters/{CLUSTER_ID}/metrics/query
Base URL

The base URL for this API is in the following format:

https://controller.api.${CLOUD_REGION}.zillizcloud.com

📘Notes
  • You need to replace ${CLOUD_REGION} with the appropriate region for your deployment.
  • To get the cloud region ID, refer to Zilliz Cloud Console or List Cloud Regions.
export CLOUD_REGION="gcp-us-west1"
export BASE_URL="https://controller.api.${CLOUD_REGION}.zillizcloud.com"
Parameters
Authorizationstringheaderrequired

The authentication token should be an API key with appropriate privileges.

Example Value: Bearer {{TOKEN}}
CLUSTER_IDstringpathrequired

The ID of the cluster.

Example Value: inxx-xxxxxxxxxxxxxxxxx
Request Bodyapplication/json
startstringrequired

The starting date and time for the metric reporting period, expressed in ISO 8601 timestamp format in UTC. Use this parameter when the period parameter is not set.

Example Value: 2023-12-31T23:59:59Z
endstringrequired

The ending date and time for the metric reporting period, expressed in ISO 8601 timestamp format in UTC. Use this parameter when the period parameter is not set.

Example Value: 2024-07-01T08:15:30Z
periodstringrequired

The duration over which the metrics are reported, expressed in ISO 8601 duration format in UTC. Use this parameter when neither start nor end parameters are not set.

granularitystringrequired

The time interval at which the metrics are reported, expressed in ISO 8601 duration format in UTC. The minimum granularity is PT30S.

metricQueriesarrayrequired

An array of MetricQuery objects.

[]metricQueriesobjectrequired

The information about the metric.

namestringrequired

The name of the metric to query. For details about available metrics, refer to Metrics & Alerts Reference.

statstringrequired

The statistical method to apply to the metric. AVG is the average value available for each metric, while P99 is the 99th percentile value for latency-related metrics.

export TOKEN="YOUR_API_KEY"
export CLUSTER_ID="inxx-xxxxxxxxxxxxxxxxx"

curl --request POST \
--url "${BASE_URL}/v1/clusters/${CLUSTER_ID}/metrics/query" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "start": "",
    "end": "",
    "period": "PT99H",
    "granularity": "PT5H",
    "metricQueries": [
        {
            "name": "CU_CAPACITY",
            "stat": "AVG"
        }
    ]
}'
Responses200 - application/json

A success response.

codeinteger

Response code.

dataobject

Response payload, which is an object containing information about the queried metric.

resultsarray

An array of result objects.

[]resultsobject

Information about the metric.

namestring

The name of the metric.

statstring

The statistical function applied to the metric.

unitstring

The unit of measurement for the metric (e.g., percent).

valuesarray

An array of data points.

[]valuesobject

A data point in detail.

timestampstring

The timestamp for the data point in ISO 8601 format.

valuestring

The value of the metric at the given timestamp.

A failure response.

codeinteger

Response code.

messagestring

Error message.

{
    "code": 200,
    "data": {
        "results": [
            {
                "name": "CU_COMPUTATION",
                "stat": "AVG",
                "unit": "percent",
                "values": [
                    {
                        "timestamp": "2024-07-23T16:09:53Z",
                        "value": "1.00"
                    },
                    {
                        "timestamp": "2024-07-23T22:09:53Z",
                        "value": "1.00"
                    },
                    {
                        "timestamp": "2024-07-24T04:09:53Z",
                        "value": "1.00"
                    }
                ]
            }
        ]
    }
}