App Environment Metrics Time Series API

The App Environment Metrics Time Series API allows you to retrieve historical metrics data from Prometheus for an app environment in Quave Cloud. Unlike the Metrics API, which returns a current snapshot, this endpoint returns time-series data that can be used for trend analysis, charting, and performance monitoring over time.

Make sure to read the Get Started document to understand how the API works.

Note: This API endpoint accepts only user tokens (not environment tokens).

Get App Environment Metrics Time Series

To retrieve historical metrics for an app environment, send a GET request to the /api/public/v1/app-env/metrics-series endpoint.

Required Parameters

Parameter	Type	Required	Description
appEnvId or envName	String	Yes	Environment identifier (provide one or the other)
metric	String	Yes	Metric type to query (see Metric Types below)

Optional Parameters

Parameter	Type	Default	Description
from	String	1 hour ago	Start time (ISO 8601 format)
to	String	now	End time (ISO 8601 format)
step	String	auto	Resolution/interval (1m, 5m, 15m, 1h)
isLive	Boolean	false	If true, returns last 30 minutes ignoring from/to

Metric Types

Value	Description	Unit
cpu_usage	CPU usage across all containers	millicores
memory_usage	Memory usage across all containers	MB
cpu_percent	CPU usage as percentage of allocated limit	percent
memory_percent	Memory usage as percentage of allocated limit	percent

Step Resolution

The step parameter controls the granularity of data points. If not specified, it's automatically calculated based on the time range:

Time Range	Default Step	Description
Under 1 hour	1m	Fine granularity for recent data
1-6 hours	5m	Good for short-term analysis
6-24 hours	15m	Good for daily analysis
Over 24 hours	1h	Best for multi-day trends

Response Structure

The response is a JSON object with the following fields:

Field	Type	Description
appEnvId	String	The app environment ID
metric	String	The metric type that was queried
from	String	Start time of the data (ISO 8601)
to	String	End time of the data (ISO 8601)
step	String	Resolution used for data points
unit	String	Unit of measurement (millicores, MB, or percent)
series	Array	Array of data points (see below)
summary	Object	Statistical summary (see below)

Series Data Points

Each item in the series array contains:

{
  "time": "2024-01-15T10:00:00.000Z",
  "value": 250.5
}

Summary Object

The summary object provides statistics for the time range:

Field	Type	Description
min	Number	Minimum value in the series
max	Number	Maximum value in the series
avg	Number	Average value across all data points
current	Number	Most recent value
dataPoints	Number	Total number of data points returned

Examples

Get CPU Usage for Last Hour

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics-series?appEnvId=xxx&metric=cpu_usage'

Get Memory Usage for Last 24 Hours

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics-series?appEnvId=xxx&metric=memory_usage&from=2024-01-14T10:00:00.000Z&to=2024-01-15T10:00:00.000Z'

Get Live CPU Percentage (Last 30 Minutes)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics-series?envName=production&metric=cpu_percent&isLive=true'

Get Memory with Custom Step Resolution

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics-series?appEnvId=xxx&metric=memory_percent&from=2024-01-15T00:00:00.000Z&to=2024-01-15T12:00:00.000Z&step=15m'

Example Response

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
  "metric": "cpu_usage",
  "from": "2024-01-15T09:00:00.000Z",
  "to": "2024-01-15T10:00:00.000Z",
  "step": "5m",
  "unit": "millicores",
  "series": [
    { "time": "2024-01-15T09:00:00.000Z", "value": 250.5 },
    { "time": "2024-01-15T09:05:00.000Z", "value": 275.2 },
    { "time": "2024-01-15T09:10:00.000Z", "value": 320.8 },
    { "time": "2024-01-15T09:15:00.000Z", "value": 290.1 },
    { "time": "2024-01-15T09:20:00.000Z", "value": 265.7 },
    { "time": "2024-01-15T09:25:00.000Z", "value": 280.3 },
    { "time": "2024-01-15T09:30:00.000Z", "value": 310.5 },
    { "time": "2024-01-15T09:35:00.000Z", "value": 295.2 },
    { "time": "2024-01-15T09:40:00.000Z", "value": 270.8 },
    { "time": "2024-01-15T09:45:00.000Z", "value": 255.4 },
    { "time": "2024-01-15T09:50:00.000Z", "value": 285.6 },
    { "time": "2024-01-15T09:55:00.000Z", "value": 300.1 }
  ],
  "summary": {
    "min": 250.5,
    "max": 320.8,
    "avg": 283.35,
    "current": 300.1,
    "dataPoints": 12
  }
}

Use Cases

1. Performance Trend Analysis

Query CPU and memory over the last 24 hours to identify patterns:

# Get CPU trends for the last 24 hours
curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics-series?appEnvId=xxx&metric=cpu_percent&from=2024-01-14T10:00:00.000Z&to=2024-01-15T10:00:00.000Z&step=1h'

2. Incident Investigation

Check what happened during a specific time window:

# High-resolution data for a 2-hour incident window
curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics-series?appEnvId=xxx&metric=memory_usage&from=2024-01-15T14:00:00.000Z&to=2024-01-15T16:00:00.000Z&step=1m'

3. Capacity Planning

Analyze peak usage over a week to plan resource allocation:

# Weekly memory trends
curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics-series?appEnvId=xxx&metric=memory_percent&from=2024-01-08T00:00:00.000Z&to=2024-01-15T00:00:00.000Z&step=1h'

4. Real-time Monitoring Dashboard

Get live data for a monitoring dashboard:

# Live CPU usage (last 30 minutes, 1-minute resolution)
curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/metrics-series?appEnvId=xxx&metric=cpu_usage&isLive=true&step=1m'

Limits and Constraints

Constraint	Value	Description
Maximum time range	7 days	Queries longer than 7 days are truncated
Default time range	1 hour	Used when from/to not specified
Live mode range	30 minutes	Fixed range when isLive=true
Maximum data points	Depends on step and range	More data points with smaller steps

Error Responses

Status	Description
400	Invalid parameters (missing metric, invalid step, etc.)
401	User not authenticated
403	User doesn't have permission to access this app environment
404	App environment not found
500	Prometheus query error (check server logs)

Example Error Response

{
  "error": "Invalid metric type: invalid_metric. Valid values are: cpu_usage, memory_usage, cpu_percent, memory_percent"
}

Understanding the Metrics

CPU Usage (millicores)

• 1000 millicores = 1 CPU core
• Value of 500 means half a CPU core is being used
• Compare with your allocated CPU to understand utilization

Memory Usage (MB)

• Memory in megabytes currently in use
• Includes working set (actively used memory)
• Compare with allocated memory to understand utilization

CPU Percent

• Calculated as: (CPU in use / CPU limit) * 100
• Values over 100% indicate throttling may occur
• Sustained high values suggest need for more resources

Memory Percent

• Calculated as: (Memory in use / Memory limit) * 100
• Values approaching 100% risk OOM (Out of Memory) kills
• Monitor trends to predict when scaling is needed

Comparison with Metrics API

Feature	Metrics API (/metrics)	Metrics Series API (/metrics-series)
Data type	Current snapshot	Historical time series
Time navigation	No	Yes (from/to/isLive)
Data source	Cached in database	Live from Prometheus
Use case	Current status	Trend analysis, debugging
Response size	Small (single values)	Larger (array of data points)
Refresh rate	~30-60 seconds	Real-time from Prometheus

Use the Metrics API for quick status checks and the Metrics Series API for detailed analysis and charting.