Overview
The Query Range API is a robust interface which enables developers to query metrics over a range of time. This API facilitates various operations:
API Endpoint
Endpoint for Query Range API:
POST https://{URL}/api/v5/query_range
Replace {URL} with your instance URL.
Prerequisites
API Keys: To access this API, you need an API key. Go to Settings → Service Accounts in SigNoz, create a service account, and generate an API key from its Keys tab. See Service Accounts for step-by-step instructions.
API keys can only be created/managed by users with the Admin role. If you don't have the Admin role, contact your organization's admin to create an API key for you.
Authentication
Using the API key: Add the API key to your request header as follows:
SIGNOZ-API-KEY:{YOUR_API_KEY}
💡 Tip
Secure storage and handling of your API key is crucial to prevent unauthorized access.
API Specification
The API specification is available in the OpenAPI Specification.
JSON Request Payload Examples
CpuUsageExample (with variables)
{
"start": 1742602572000,
"end": 1742604372000,
"requestType": "time_series",
"variables": {
"k8s.node.name": {
"type": "custom",
"value": [
"gke-application-eu-c-pl-addon-n2dhc4--c80039c0-2gjz"
]
},
"k8s.cluster.name": {
"type": "custom",
"value": "application-eu-central"
}
},
"formatOptions": {
"fillGaps": false
},
"compositeQuery": {
"queries": [
{
"type": "builder_query",
"spec": {
"name": "A",
"signal": "metrics",
"stepInterval": 60,
"aggregations": [
{
"metricName": "k8s.node.cpu.usage",
"temporality": "Unspecified",
"timeAggregation": "avg",
"spaceAggregation": "sum"
}
],
"filter": {
"expression": "k8s.cluster.name = $k8s.cluster.name AND k8s.node.name in $k8s.node.name"
},
"groupBy": [
{
"name": "k8s.node.name",
}
],
"legend": "{{k8s.node.name}}",
"disabled": false
}
}
]
}
}
HttpDurationExample (querying histogram metric)
{
"start": 1742602968000,
"end": 1742604768000,
"requestType": "time_series",
"compositeQuery": {
"queries": [
{
"type": "builder_query",
"spec": {
"name": "A",
"signal": "metrics",
"stepInterval": 60,
"aggregations": [
{
"metricName": "jvm.gc.duration.bucket",
"spaceAggregation": "p90"
}
],
"groupBy": [
{
"name": "service.name",
}
],
"legend": "{{service.name}}",
"disabled": false
}
}
]
}
}
MemoryUsedExample (with variables)
{
"start": 1742603085000,
"end": 1742604885000,
"requestType": "time_series",
"variables": {
"k8s.node.name": {
"type": "custom",
"value": [
"gke-application-pl-addon-n2dhc4-od-71879e78-0ql9"
]
},
"k8s.cluster.name": {
"type": "custom",
"value": "application"
}
},
"compositeQuery": {
"queries": [
{
"type": "builder_query",
"spec": {
"name": "A",
"signal": "metrics",
"stepInterval": 60,
"aggregations": [
{
"metricName": "k8s.node.memory.usage",
"timeAggregation": "avg",
"spaceAggregation": "sum"
}
],
"filter": {
"expression": "k8s.cluster.name = $k8s.cluster.name AND k8s.node.name IN $k8s.node.name"
},
"groupBy": [
{
"name": "k8s.node.name",
}
],
"legend": "used",
"disabled": false
}
}
]
}
}
RequestCountExample
{
"start": 1742603295000,
"end": 1742605095000,
"requestType": "time_series",
"compositeQuery": {
"queries": [
{
"type": "builder_query",
"spec": {
"name": "A",
"signal": "metrics",
"stepInterval": 60,
"aggregations": [
{
"metricName": "signoz_calls_total",
"timeAggregation": "rate",
"spaceAggregation": "sum"
}
],
"groupBy": [
{
"name": "service.name",
}
],
"legend": "{{service.name}}",
"disabled": false
}
}
]
}
}
ErrorRateExample (using formula with one or more queries)
{
"start": 1742601948000,
"end": 1742605548000,
"requestType": "time_series",
"compositeQuery": {
"queries": [
{
"type": "builder_query",
"spec": {
"name": "A",
"signal": "metrics",
"stepInterval": 60,
"aggregations": [
{
"metricName": "signoz_calls_total",
"timeAggregation": "rate",
"spaceAggregation": "sum"
}
],
"filter": {
"expression": "status.code = 'STATUS_CODE_ERROR'"
},
"groupBy": [
{
"name": "service.name",
"dataType": "string",
"type": "tag"
}
],
"legend": "{{service.name}}",
"disabled": true
}
},
{
"type": "builder_query",
"spec": {
"name": "B",
"signal": "metrics",
"stepInterval": 60,
"aggregations": [
{
"metricName": "signoz_calls_total",
"timeAggregation": "rate",
"spaceAggregation": "sum"
}
],
"groupBy": [
{
"name": "service.name",
}
],
"disabled": true
}
},
{
"type": "builder_formula",
"spec": {
"name": "F1",
"expression": "A/B",
"disabled": false
}
}
]
}
}
