Query Metrics

Execute PromQL queries against groundcover metrics data. Two endpoints are available: instant queries for point-in-time values and range queries for time-series data over specific periods.

Endpoints

Instant Query

GET /api/prometheus/api/v1/query

Execute an instant PromQL query to get metric values at a single point in time.

Range Query

POST /api/metrics/query-range

Execute a PromQL query over a time range to get time-series data.

Authentication

Both endpoints require API Key authentication via the Authorization header.

Instant Query Endpoint

Request

GET /api/prometheus/api/v1/query

Headers

Authorization: Bearer <YOUR_API_KEY>
Accept: application/json

Query Parameters

Parameter	Type	Required	Description
query	string	Yes	PromQL query string (URL encoded)
time	string	No	Single point in time to evaluate the query (RFC3339 format). Default: current time

Understanding the Time Parameter

The time parameter specifies exactly one timestamp at which to evaluate your PromQL expression. This is NOT a time range:

• With time: "What was the disk usage at 2025-10-21T09:21:44.398Z?"

• Without time: "What is the disk usage right now?"

Important: This is different from range queries which return time-series data over a period.

Instant vs Range Queries - Key Differences

Aspect	Instant Query	Range Query
Purpose	Get value at one specific moment	Get time-series data over a period
Time Parameter	Single timestamp (time)	Start and end timestamps (start, end)
Result	One data point	Multiple data points over time
Use Case	"What is the current CPU usage?"	"Show me CPU usage over the last hour"
Response	Single value with timestamp	Array of timestamp-value pairs

Example Comparison:

• Instant: time=2025-10-21T09:00:00Z → Returns disk usage at exactly 9:00 AM

• Range: start=2025-10-21T08:00:00Z&end=2025-10-21T09:00:00Z → Returns hourly disk usage trend

Practical Example:

# Get current value (no time parameter)
# Returns: {"value":[1761040224,"18.45"]} - timestamp is "right now"
curl '...query=avg(groundcover_node_rt_disk_space_used_percent{})' 

# Get historical value (with time parameter) 
# Returns: {"value":[1761038504,"18.44"]} - timestamp is exactly what you specified
curl '...query=avg(groundcover_node_rt_disk_space_used_percent{})&time=2025-10-21T09:21:44.398Z'

Response

The endpoint returns a Prometheus-compatible response format:

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {},
        "value": [1761038504.398, "18.442597642017"]
      }
    ]
  },
  "stats": {
    "seriesFetched": "12",
    "executionTimeMsec": 0
  }
}

Response Fields

Field	Type	Description
status	string	Query execution status ("success" or "error")
data.resultType	string	Type of result data ("vector", "matrix", "scalar", "string")
data.result	array	Array of metric results
data.result[].metric	object	Metric labels as key-value pairs
data.result[].value	array	[timestamp, value] tuple with Unix timestamp and string value
stats.seriesFetched	string	Number of time series processed
stats.executionTimeMsec	number	Query execution time in milliseconds

Range Query Endpoint

Request

POST /api/metrics/query-range

Headers

Authorization: Bearer <YOUR_API_KEY>
Accept: application/json
Content-Type: application/json

Request Body

{
  "promql": "string",
  "start": "string",
  "end": "string", 
  "step": "string"
}

Request Parameters

Parameter	Type	Required	Description
promql	string	Yes	PromQL query expression
start	string	Yes	Range start time in RFC3339 format
end	string	Yes	Range end time in RFC3339 format
step	string	Yes	Query resolution step (e.g., "30s", "1m", "5m", "1h")

Response

The range query returns a custom format optimized for time-series data:

{
  "velocities": [
    {
      "velocity": [
        [1760950800, "21.534558665381155"],
        [1760952600, "21.532404350483848"],
        [1760954400, "21.57135294176692"]
      ],
      "metric": {}
    }
  ],
  "promql": "avg(groundcover_node_rt_disk_space_used_percent{})"
}

Response Fields

Field	Type	Description
velocities	array	Array of time-series data objects
velocities[].velocity	array	Array of [timestamp, value] data points
velocities[].metric	object	Metric labels as key-value pairs
promql	string	Echo of the executed PromQL query

Each data point in the velocity array contains:

• Timestamp: Unix timestamp as integer

• Value: Metric value as string

Examples

Instant Query Examples

Current Values (No Time Parameter)

Get current average disk space usage (evaluated at request time):

curl 'https://app.groundcover.com/api/prometheus/api/v1/query?query=avg%28groundcover_node_rt_disk_space_used_percent%7B%7D%29' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>'

Historical Point-in-Time Values

Get disk usage at a specific moment in the past:

curl 'https://app.groundcover.com/api/prometheus/api/v1/query?query=avg%28groundcover_node_rt_disk_space_used_percent%7B%7D%29&time=2025-10-21T09%3A21%3A44.398Z' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>'

Note: This returns the disk usage value at exactly 2025-10-21T09:21:44.398Z, not a range from that time until now.

Range Query Examples

24-Hour Disk Usage Trend

Get disk usage over the last 24 hours with 30-minute resolution:

curl 'https://app.groundcover.com/api/metrics/query-range' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'content-type: application/json' \
  --data-raw '{
    "promql": "avg(groundcover_node_rt_disk_space_used_percent{})",
    "start": "2025-10-20T09:19:22.475Z",
    "end": "2025-10-21T09:19:22.475Z",
    "step": "1800s"
  }'

High-Resolution CPU Monitoring

Monitor CPU usage over 1 hour with 1-minute resolution:

curl 'https://app.groundcover.com/api/metrics/query-range' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'content-type: application/json' \
  --data-raw '{
    "promql": "avg(groundcover_cpu_usage_percent) by (cluster)",
    "start": "2025-10-21T08:00:00.000Z",
    "end": "2025-10-21T09:00:00.000Z", 
    "step": "1m"
  }'

Query Optimization

1. Use appropriate time ranges: Avoid querying excessively large time ranges

2. Choose optimal step sizes: Balance resolution with performance

3. Filter early: Use label filters to reduce data volume

4. Aggregate wisely: Use grouping to reduce cardinality

Time Handling

1. Use RFC3339 format: Always use ISO 8601 timestamps

2. Account for timezones: Timestamps are in UTC

3. Align step boundaries: Choose steps that align with data collection intervals

4. Handle clock skew: Allow for small time differences in distributed systems

Rate Limiting

• Concurrent queries: Limit concurrent requests to avoid overwhelming the API

• Query complexity: Complex queries may take longer and consume more resources

• Data retention: Historical data availability depends on your retention policy