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 ONE. 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
`groupBy`	String	`environment`	Use `pod` to return a separate series and summary for every replica

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)

The default groupBy=environment response keeps the aggregate series contract above. With groupBy=pod, the response instead includes:

Field	Type	Description
`groupBy`	String	`pod`
`labelName`	String	`pod`, identifying the Prometheus label used as the key
`seriesByLabel`	Object	Time-series arrays keyed by the stable Kubernetes pod name
`summaryByLabel`	Object	`min`, `max`, `avg`, `current`, and `dataPoints` for each pod

Per-pod grouping works the same way for regular application replicas and managed database replicas.

Pod-Level Baseline and Account Summaries

The related /api/public/v1/app-env/metrics-baseline-summary and /api/public/v1/account/observability-summary endpoints also accept groupBy=pod. In that mode, every metric includes summaryByLabel keyed by pod name. Each pod entry contains separate baseline, recent, and deviation objects. Current pods use their own history when available. After a rollout changes pod names, baselineSource: "allBaselinePods" means the current pod is compared with the pooled per-pod baseline instead; terminated pods without data at the freshest recent sample are not returned as current results. For a pooled baseline, last is the mean across pods at the freshest baseline sample rather than an arbitrary pod's value. Omitting groupBy preserves each endpoint's aggregate response.

{
  "groupBy": "pod",
  "labelName": "pod",
  "metrics": [
    {
      "metric": "memory_usage",
      "unit": "MB",
      "summaryByLabel": {
        "my-app-7d9f8b6c5f-a1b2c": {
          "baselineSource": "matchingPod",
          "baseline": { "mean": 580.2, "last": 590.1 },
          "recent": { "mean": 612.8, "last": 621.4 },
          "deviation": {
            "absoluteDelta": 32.6,
            "percentDelta": 5.62,
            "zScore": 1.34
          }
        }
      }
    }
  ]
}

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'

Get Actual Memory Usage for Every Replica

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

The most recent memory value for each replica is available at summaryByLabel[<pod-name>].current in MB. Use the same groupBy=pod option with cpu_usage, cpu_percent, or memory_percent.

Example Per-Pod Response

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
  "metric": "memory_usage",
  "groupBy": "pod",
  "labelName": "pod",
  "unit": "MB",
  "seriesByLabel": {
    "my-app-7d9f8b6c5f-a1b2c": [
      { "time": "2026-08-22T10:00:00.000Z", "value": 610.4 }
    ],
    "my-app-7d9f8b6c5f-d3e4f": [
      { "time": "2026-08-22T10:00:00.000Z", "value": 721.8 }
    ]
  },
  "summaryByLabel": {
    "my-app-7d9f8b6c5f-a1b2c": {
      "min": 598.2,
      "max": 614.7,
      "avg": 606.1,
      "current": 610.4,
      "dataPoints": 31
    },
    "my-app-7d9f8b6c5f-d3e4f": {
      "min": 701.3,
      "max": 725.1,
      "avg": 713.6,
      "current": 721.8,
      "dataPoints": 31
    }
  }
}

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
Per-replica usage	No	Yes, with `groupBy=pod`
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.

Get App Environment Metrics Time Series​

Required Parameters​

Optional Parameters​

Metric Types​

Step Resolution​

Response Structure​

Pod-Level Baseline and Account Summaries​

Series Data Points​

Summary Object​

Examples​

Get CPU Usage for Last Hour​

Get Memory Usage for Last 24 Hours​

Get Live CPU Percentage (Last 30 Minutes)​

Get Memory with Custom Step Resolution​

Get Actual Memory Usage for Every Replica​

Example Per-Pod Response​

Example Response​

Use Cases​

1. Performance Trend Analysis​

2. Incident Investigation​

3. Capacity Planning​

4. Real-time Monitoring Dashboard​

Limits and Constraints​

Error Responses​

Example Error Response​

Understanding the Metrics​

CPU Usage (millicores)​

Memory Usage (MB)​

CPU Percent​

Memory Percent​

Comparison with Metrics API​