Latest metrics
Endpoint: /api/metrics/latest/
One request returns a page of servers with each server’s newest CPU, memory, disk usage, disk I/O, and network value—the same numbers behind the workspace’s metrics overview. It accepts the same filters, search, and pagination as the server list, so you can page through, search, or narrow a fleet and read many servers’ latest numbers in one call instead of querying each server on its own.
Requires the Metrics extension to be enabled for the workspace: a plan that doesn’t reach it answers 402, and a plan that reaches it but hasn’t switched it on answers 403. Requires metric:read.
Request
GET /api/metrics/latest/Query parameters
Accepts every filter, search field, and pagination parameter the server list does—name, groups, tag, is_connected, starred, os, search, and the rest of that table—plus:
| Parameter | Type | Description |
|---|---|---|
state | string | stale—servers whose newest sample, across all five metrics, is too old to trust, or missing entirely. no_data—servers with no stored sample for any metric yet. Every no_data server is also stale |
ordering | string | Extends the server list’s own ordering with sampled_at and the five metric families: cpu, memory, disk-usage (or disk_usage), disk-io (or disk_io), net. Prefix any of them with - for descending. Also accepts metric_severity and -metric_severity (see Server severity). Default: starred servers first, in their saved order, then name |
page | integer | Page number |
page_size | integer | Results per page (default: 15, max: 100) |
Response
{
"count": 42,
"current": 1,
"next": 2,
"previous": null,
"last": 3,
"summary": {
"critical": 3,
"warning": 7,
"stale": 4,
"no_data": 1
},
"results": [
{
"id": "0f3c9d2e-1a4b-4c8d-9e6f-2b7a1c5d8e30",
"name": "web-01",
"is_connected": true,
"metric_severity": "warning",
"cpu": {
"value": 42.1,
"unit": "percent",
"sampled_at": "2026-09-17T02:14:00+09:00",
"device": null,
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": 80.0,
"operator": "gte"
},
"memory": {
"value": 68.4,
"unit": "percent",
"sampled_at": "2026-09-17T02:14:00+09:00",
"device": null,
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": 90.0,
"operator": "gte"
},
"disk-usage": {
"value": 78.0,
"unit": "percent",
"sampled_at": "2026-09-17T02:14:00+09:00",
"device": "/",
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": 85.0,
"operator": "gte"
},
"disk-io": {
"value": 12582912.0,
"unit": "bytes_per_sec",
"sampled_at": "2026-09-17T02:14:00+09:00",
"device": "all",
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": null,
"operator": null
},
"net": {
"value": 3145728.0,
"unit": "bytes_per_sec",
"sampled_at": "2026-09-17T02:14:00+09:00",
"device": "all",
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": null,
"operator": null
}
},
{
"id": "3b8f4c1a-7d2e-4a9b-8c5f-1e6a2b9d4c7f",
"name": "db-01",
"is_connected": true,
"metric_severity": null,
"cpu": {
"value": 12.3,
"unit": "percent",
"sampled_at": "2026-09-17T02:13:00+09:00",
"device": null,
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": null,
"operator": null
},
"memory": {
"value": null,
"unit": "percent",
"sampled_at": null,
"device": null,
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": null,
"operator": null
},
"disk-usage": {
"value": 34.5,
"unit": "percent",
"sampled_at": "2026-09-17T02:13:00+09:00",
"device": "/data",
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": null,
"operator": null
},
"disk-io": {
"value": 512000.0,
"unit": "bytes_per_sec",
"sampled_at": "2026-09-17T02:13:00+09:00",
"device": "all",
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": null,
"operator": null
},
"net": {
"value": 204800.0,
"unit": "bytes_per_sec",
"sampled_at": "2026-09-17T02:13:00+09:00",
"device": "all",
"collected": true,
"reason": null,
"interval_s": 60,
"threshold": null,
"operator": null
}
}
]
}Every entry in results carries id, name, is_connected, metric_severity, and one object per metric family: cpu, memory, disk-usage, disk-io, net. unit is percent for CPU, memory, and disk usage, and bytes_per_sec for disk I/O and network. device names the disk or interface the value came from—the specific mount point for disk usage, all for the combined disk I/O or network total, and null for CPU and memory, which aren’t device-specific.
Cell thresholds
Each metric object includes these fields:
| Field | Type | Description |
|---|---|---|
threshold | number or null | Effective rule threshold after the server’s rule override applies, in the cell’s unit |
operator | string or null | gte for a value at or above the threshold, lte for a value at or below it |
For cpu, memory, and disk-usage, both fields are null when no rule applies to the cell, including when the server is not commissioned (commissioned=false) or is disabled, or its applicable rules are disabled by server overrides. If several rules apply, gte takes precedence over lte; the lowest gte threshold or highest lte threshold is returned. A disk rule with a device selector applies only when it matches the disk represented by the cell.
For disk-io and net, both fields are always null. These cells sum both directions across devices, while rules evaluate one direction per device.
Reading thresholds requires permission to read rule overrides and the rule_override:read token scope. Without that access, threshold and operator are null on every cell.
Server severity
| Field | Type | Description |
|---|---|---|
metric_severity | string or null | Highest severity among the server’s open metric_threshold alerts: critical, warning, then info. null when there is no such alert or the caller cannot read alerts |
ordering=-metric_severity sorts critical first, then warning, info, and null across all pages. ordering=metric_severity reverses that order. Ties follow the default server order.
Without alert read access, including the alert:read token scope, metric_severity, summary.critical, and summary.warning are null, and severity ordering is ignored. Threshold visibility is controlled separately by rule-override read access.
Summary
The top-level summary counts servers in the full filtered set that the caller can see, before pagination. Search and state filters apply to these counts too. These are server counts, not alert counts.
| Field | Type | Description |
|---|---|---|
critical | integer or null | Servers whose metric_severity is critical. null without alert read access |
warning | integer or null | Servers whose metric_severity is warning, excluding servers counted as critical. null without alert read access |
stale | integer | Servers matching state=stale, including those with no data |
no_data | integer | Servers with no stored sample for any metric, matching state=no_data |
Every no_data server also counts in stale. The stale and no_data counts remain available without alert:read.
Required scope: metric:read
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/metrics/latest/?is_connected=true&ordering=-cpu" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""When a cell is empty
When no sample has arrived for a family yet, its value, sampled_at, and device are null. This can happen on a newly registered server or for a metric that has never reported. interval_s says how often, in seconds, a sample should arrive for that family.
collected is true and reason is null on every cell you’ll see here: reaching this endpoint at all already means the Metrics extension is enabled for the workspace, so there’s no case where a family it reports is not being collected.
Finding the busiest or quietest host
Sort on any metric family with ordering. Descending finds the busiest server first, ascending finds the quietest:
# Highest CPU first
curl -X GET "https://your-workspace.us1.alpacon.io/api/metrics/latest/?ordering=-cpu" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
# Lowest disk usage first
curl -X GET "https://your-workspace.us1.alpacon.io/api/metrics/latest/?ordering=disk-usage" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""A server with no value for the family you’re sorting on sorts last, whichever direction you use—a fleet ordered by -net never opens with a server that hasn’t reported any network traffic at all. Combine with state=stale or state=no_data to separate servers that are behind from ones that just rank low.
Error responses
| Status | Error code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Invalid or missing authentication |
| 402 | workspace_extension_plan_required | The workspace’s plan doesn’t include the Metrics extension |
| 403 | workspace_extension_not_enabled | The Metrics extension is available on this plan but hasn’t been switched on |