Metrics service
The metrics service provides resources for retrieving collected time series metric data, aggregated into the intervals you specify. To work with the definitions that describe what a metric measures, use the metric resources of the dictionary service.
Resource list
Search for metric data (POST /v1/metrics:search)
POST /v1/metrics:search
Return time series metric data for a single entity, aggregated into fixed-length periods.
Note
This endpoint returns data for the first entity that matches entityClause only. Pagination doesn't advance to a second entity. Write entityClause so that it identifies one entity. If it matches more than one, the results are incomplete and no error is returned.
The field value in a filter must match a field key defined on the tenant's entities. To list the available keys, use the list default fields and field sources resource of the model management service. The fieldSources map in that response classifies each key as a property, a core property, or a dimension. Prefix core property keys with coreProperties. and dimension keys with dimensions. when you reference them in a filter. Property keys, such as source, device, and name, take no prefix.
Request template
An abstract preview of a JSON request that returns hourly averages for one entity.
{
"entityClause": {
"and": {
"clauses": [
{
"filter": {
"field": "<entity-field>",
"operation": "<operation>",
"value": "<value>"
}
}
]
}
},
"metricClause": {
"filter": {
"field": "<metric-field>",
"operation": "<operation>",
"value": "<value>"
}
},
"timeRange": {
"start": "<timestamp>",
"end": "<timestamp>"
},
"downsample": {
"aggregator": "<aggregator>",
"period": "<duration>"
},
"pageSize": <integer>,
"pageToken": "<token>"
}Request fields
Field | Type | Required | Description |
|---|---|---|---|
| object | Yes | The criteria that identify the entity to return metric data for. The object contains exactly one clause. For the clause types and the fields each one takes, see Clause types. |
| object | No | The criteria that select which of the entity's metrics to return. The object contains exactly one clause and takes the same form as |
| object | Yes | The period of time to return metric data for. |
| string | Yes | The beginning of the period, as a timestamp. For example, |
| string | Yes | The end of the period, as a timestamp. For example, |
| object | Yes | The aggregation to apply to the data points before they're returned. |
| string | Yes | The function that combines the data points in each period. Accepted values:
You can send the equivalent numeric value instead of the name, but the name is clearer and is used throughout this documentation. |
| string | Yes | The length of each aggregation period, as a duration. For example, |
| integer | No | The maximum number of metrics to return in one page of results. |
| string | No | The token that identifies the page of results to return. Use the |
Clause types
The entityClause and metricClause fields each take an object that contains exactly one of the following clauses. The and, or, and not clauses contain other clauses and can be nested to any depth. The remaining clauses are single comparisons.
Clause | Description |
|---|---|
| Matches only when every clause in the |
| Compares one field to one value. Takes a
In a You can send the equivalent numeric value instead of the operation name, but the name is clearer and is used throughout this documentation. |
| Matches when the |
| Matches only when the clause in the |
| Matches when any clause in the |
| Matches when the field in the |
| Matches the entities whose identifiers appear in the |
The following examples show each clause type.
{ "and": { "clauses": [
{ "filter": { "field": "source", "operation": "OP_EQUALS", "value": "cz0" } },
{ "filter": { "field": "device", "operation": "OP_EQUALS", "value": "192.0.2.10" } }
] } }
{ "or": { "clauses": [
{ "filter": { "field": "name", "operation": "OP_EQUALS", "value": "eth0" } },
{ "filter": { "field": "name", "operation": "OP_EQUALS", "value": "eth1" } }
] } }
{ "not": { "clause":
{ "filter": { "field": "source", "operation": "OP_EQUALS", "value": "cz0" } }
} }
{ "filter": { "field": "device", "operation": "OP_EQUALS", "value": "192.0.2.10" } }
{ "in": { "field": "device", "values": ["192.0.2.10", "192.0.2.11"] } }
{ "withIds": { "ids": ["AAAAAYcLE4UpjDUTWVU8_OnSvBQ="] } }
{ "range": { "path": "createdTime", "gte": 1784216459000, "lt": 1784302859000 } }Response fields
Field | Description |
|---|---|
| An array of the metrics that matched the search. |
| A string that uniquely identifies the metric. |
| The display name of the metric. |
| An object that holds the metric's definition metadata. For its fields, see Dictionary fields. |
| An array of strings, each the time of one data point in milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC). |
| An array of numbers, each the value of the data point at the matching position in |
| The token that identifies the next page of results. The value is empty on the last page. |
Dictionary fields
Field | Description |
|---|---|
| An object that holds the default version of a tenant-specific metric. The object takes the same form as |
| An array of the fields used to group the metric for aggregation by default. |
| A long-form description of the metric. |
| A boolean that indicates whether to display the metric as a rate rather than as its raw cumulative value. |
| A short, human-readable label for the metric. |
| The layer the metric definition comes from. Values:
|
| The highest likely value for the metric. The value is |
| The lowest likely value for the metric. The value is |
| The name that uniquely identifies the metric within its layer. |
| The number that converts the time series data to the unit named in |
| The string form of |
| The name of the unit that applies after |
| An array of arbitrary strings associated with the metric. |
| The unit of measure for the metric, such as bytes, percent, or milliseconds. |
Response codes
Code | Description |
|---|---|
200 | The request was processed successfully. For operations on multiple objects, check the response body for per-item results. |
400 | The request couldn't be processed. The request body is missing, malformed, or contains invalid values. |
401 | Authentication failed. The API key is missing or invalid. |
500 | An unexpected error occurred. Try the request again. If the problem persists, contact Virtana support. |
Examples
curl https://YOUR-API-ENDPOINT/v1/metrics:search \
-H "content-type: application/json" \
-H "zenoss-api-key: YOUR-API-KEY" \
-X POST -s -S -d \
'{
"entityClause": {
"and": {
"clauses": [
{
"filter": {
"field": "source",
"operation": "OP_EQUALS",
"value": "cz0"
}
},
{
"filter": {
"field": "device",
"operation": "OP_EQUALS",
"value": "192.0.2.10"
}
},
{
"filter": {
"field": "name",
"operation": "OP_EQUALS",
"value": "br-232dcdc111e6"
}
}
]
}
},
"timeRange": {
"start": "2026-07-16T15:40:59.000Z",
"end": "2026-07-17T15:40:59.000Z"
},
"downsample": {
"aggregator": "MEAN",
"period": "3600s"
}
}'