Latest metrics

Endpoint: /api/metrics/latest/

One request that returns a page of servers, each with its 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:

Response

{
  "count": 42,
  "current": 1,
  "next": 2,
  "previous": null,
  "last": 3,
  "results": [
    {
      "id": "0f3c9d2e-1a4b-4c8d-9e6f-2b7a1c5d8e30",
      "name": "web-01",
      "is_connected": true,
      "cpu": {
        "value": 42.1,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "memory": {
        "value": 68.4,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "disk-usage": {
        "value": 78.0,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:14:00+09:00",
        "device": "/",
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "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
      },
      "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
      }
    },
    {
      "id": "3b8f4c1a-7d2e-4a9b-8c5f-1e6a2b9d4c7f",
      "name": "db-01",
      "is_connected": true,
      "cpu": {
        "value": 12.3,
        "unit": "percent",
        "sampled_at": "2026-09-17T02:13:00+09:00",
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "memory": {
        "value": null,
        "unit": "percent",
        "sampled_at": null,
        "device": null,
        "collected": true,
        "reason": null,
        "interval_s": 60
      },
      "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
      },
      "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
      },
      "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
      }
    }
  ]
}

Every entry in results carries id, name, is_connected, 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.

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

A family’s value, sampled_at, and device are null exactly when no sample has arrived for it yet—a server just registered, or a metric that hasn’t reported since. 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