# VM host capacity — integration contract

Use this document to build a reseller capacity-planning client. The human page is https://portal.rackcorp.com/docs/monitoring.html. This file is the source of truth for agents.

Base URL: `https://api.rackcorp.net/api/rest/v2.10`

Auth: `Authorization: Bearer <JWT>`. Get a JWT with `session.login` and `"jwt": 1`, or `POST /customer/jsonwebtoken`.

Command call (preferred):

```http
POST /json.php
Content-Type: application/json

{"cmd":"<command>", ...fields}
```

These responses put `matches`, `devices`, `hosts`, or `vms` on the **top-level JSON object next to `code` and `message`**. Do not look for them under `data`.

## Hard rules

1. Fleet capacity is `device.vmhost.availability.getall` (`GET /devices/vmhoststatus`). Call it **once per account, no more often than every 300 seconds**. The numbers change about once a minute. Faster polling returns the same row.
2. Host free CPU, RAM, and disk are **not stored as history**. To trend them, save the snapshot yourself (every 900 seconds is enough).
3. `monitoring.data.get` reads RRD tables. **Do not put it on a timer. Do not loop it across VMs or series.** One call is one `deviceid` and one `snmpid`, and only when a person opens a chart or a small nightly export runs. Prefer a window of 8 hours or longer.
4. Prometheus uses `GET /devices/vmhost/prometheus` (`device.vmhost.prometheus.getall`). It is the fleet snapshot in text format. A scraper should use HTTP Basic (`API UUID` / `API secret`), not a JWT (a JWT expires). Set `scrape_interval` to **5 minutes**. The API reuses the rendered body for 300 seconds per customer, so a shorter interval does not repeat the query. Each `device_id` is emitted once. Human setup guide: https://portal.rackcorp.com/docs/prometheus.html
5. There is no `metric` or `interval` parameter. Do not invent one.
6. Drop rows with `outOfDate: true` (host silent for 20 minutes) and storage rows with `stale: true` (inventory older than 15 minutes).

The API does not currently reject a client that polls faster. Stay inside the ceilings anyway.

## Pull ceilings

| Command | Min interval | Notes |
| --- | --- | --- |
| `device.vmhost.availability.getall` | 300s, once per account | Useful ceiling is 60s because that is the sample period. Use 300–900s for planning. |
| `GET /devices/vmhost/prometheus` | 300s, once per account | Same rows as the fleet snapshot. Cached for 300s. |
| `device.vmhost.get` | 900s | Inventory only. |
| `storage.vmhstorage.getall` | 600s, once per account | Source updates every 300s. |
| `device.vmhost.vms.get` | 300s **per host**, on demand | Do not walk every host on a timer. |
| `monitoring.metrics.get` | 300s **per VM**, on demand | Point lookup. Not a fleet sweep. |
| `monitoring.data.get` | not scheduled | Chart open or a few series per night. |

## Recommended loop

```text
every 900s:
  snapshot = POST {"cmd":"device.vmhost.availability.getall"}
  store snapshot.devices where outOfDate is false
  pools = POST {"cmd":"storage.vmhstorage.getall"}
  store pools.hosts where stale is false

when a user opens host H:
  if cache miss or cache older than 300s:
    POST {"cmd":"device.vmhost.vms.get","vmhostDeviceId":H,"role":"ANY"}

when a user opens a chart for VM V and series S:
  POST {"cmd":"monitoring.data.get","deviceid":V,"snmpid":S,"fromtime":...,"totime":...}
  cache for the session
```

Permissions: snapshot and VM list need device access. Guest metrics and RRD need monitoring access. Pool bytes need storage access. The Prometheus scrape is allowed for a key that has `device.vmhost.prometheus.getall`, `device.vmhost.availability.getall`, or `device.*`.

## Prometheus

Human page: https://portal.rackcorp.com/docs/prometheus.html

One job. Target host and path are separate. The path must start with `/` and the first segment is `devices` (plural).

```yaml
scrape_configs:
  - job_name: devicevmhost
    scheme: https
    metrics_path: /api/rest/v2.10/devices/vmhost/prometheus
    scrape_interval: 5m
    scrape_timeout: 30s
    basic_auth:
      username: API_UUID
      password_file: /etc/prometheus/rackcorp_api_secret
    static_configs:
      - targets:
          - api.rackcorp.net
```

A successful body is `text/plain; version=0.0.4` and starts with `# HELP`. `X-Rackcorp-Scrape-Cache` is `miss` when the query ran and `hit` when the 300s body was reused. A JSON body means the path is wrong or the key cannot call the command.

Each series is one sample per `device_id`. `rackcorp_device_vm_total{device_id="24657"}` appears once. The value `80` is the planning cap, not the running count. Running guests are `rackcorp_device_vm_used`. A second availability row for the same device is dropped so Prometheus does not reject the scrape for a duplicate sample. If a query still returns two series for one `device_id`, compare `job` and `instance`: a second scrape job or a second Prometheus remote-writing into the same TSDB produced the extra series.

```promql
count by (device_id, job, instance) (rackcorp_device_vm_total)
count by (device_id) (rackcorp_device_vm_total) > 1
```

The second query is empty when only one job scrapes this URL.

Gauges, label `device_id` unless noted. `rackcorp_device_info` is always 1 and carries `device_name`, `dc_short`, `dc_name`, `dc_id`, `svc_info`, `svc_description`, `vmh_version`. Join it with `* on (device_id) group_left(device_name, dc_short)`.

| Metric | Meaning |
| --- | --- |
| `rackcorp_device_cpu_total_cores` / `_free_cores` / `_used_cores` | Logical cores. Idle ratio is `free / total`. |
| `rackcorp_device_cpu_utilization_ratio` | `used / total`, 0..1. |
| `rackcorp_device_cpu_status_code` | 0 OK, 1 WARNING (under 30% idle), 2 CRITICAL (under 20% idle). |
| `rackcorp_device_memory_*_bytes` | Bytes. `free` is headroom after a 32 GB reserve, not `total - used`. |
| `rackcorp_device_memory_status_code` | With swap known: OK at or under 10% of RAM oversubscribed, WARNING above 10, CRITICAL above 40. |
| `rackcorp_device_storage_*_bytes` | Bytes. `free` is 0 when reported free is under 64 GB. |
| `rackcorp_device_storage_status_code` | WARNING under 500 GB free, CRITICAL under 100 GB. |
| `rackcorp_device_raid_healthy` | 1 healthy, 0 not. |
| `rackcorp_device_traffic_*_bits_per_second` | Also labelled `direction="inbound"` or `"outbound"`. Divide by `1000^2` for Mbit/s. |
| `rackcorp_device_traffic_status_code` | WARNING under 200 Mbit/s free, CRITICAL under 100. |
| `rackcorp_device_vm_used` | Running guests. |
| `rackcorp_device_vm_total` | Planning soft cap of 80, not a scheduler limit. |
| `rackcorp_device_vm_free` | `80 - used`. |
| `rackcorp_device_vm_status_code` | WARNING at 70 used, CRITICAL at 80. |
| `rackcorp_device_out_of_date` | 1 when the host has not checked in for 20 minutes. |
| `rackcorp_device_incident` | 1 when the host row is flagged with an incident. |

Status code `-1` is anything other than OK, WARNING, CRITICAL, or ERROR. `rackcorp_exporter_build_info` is 1 with a `version` label. `rackcorp_exporter_scrape_duration_seconds` is the render time of the stored body, so it stays flat on a cache hit.

This scrape is not per-VM metrics and it is not `monitoring.data.get`.

## device.vmhost.availability.getall

REST: `GET /devices/vmhoststatus`

```json
{"cmd":"device.vmhost.availability.getall"}
```

No parameters. One object per active VM host.

```json
{
  "code": "OK",
  "message": "Successfully Retrieved Stats",
  "matches": 1,
  "devices": [
    {
      "deviceId": 12345,
      "deviceName": "vmh12",
      "dcId": 4,
      "dcName": "Sydney",
      "dcShort": "SYD1",
      "vmhVersion": "1.4.2",
      "outOfDate": false,
      "svcInfo": "N/A",
      "svcDescription": "DHCPOK NICSOK DISKOK",
      "svcCodes": ["DHCPOK", "NICSOK", "DISKOK"],
      "network_status": "OK",
      "network_nics_up": 2,
      "network_nics_down": 0,
      "network_nics_total": 2,
      "storage": {"free": 2400, "used": 18000, "total": 21000, "status": "OK", "unit": "GB", "raidStatus": true, "type": "storage"},
      "memory": {"free": 80, "used": 400, "total": 512, "status": "OK", "unit": "GB", "type": "memory", "swapUsed": 2, "swapTotal": 64, "swapFree": 62, "oversubscribePct": 0.4, "combinedPct": 69.8},
      "cpu": {"free": 40, "used": 8, "total": 48, "status": "OK", "unit": "%", "type": "cpu"},
      "trafficInbound": {"free": 860, "used": 140, "total": 1000, "status": "OK", "unit": "Mbit/s", "type": "bandwidth"},
      "trafficOutbound": {"free": 910, "used": 90, "total": 1000, "status": "OK", "unit": "Mbit/s", "type": "bandwidth"},
      "vmCount": {"free": 55, "used": 25, "total": 80, "status": "OK", "unit": "VMs", "type": "vmCount"}
    }
  ]
}
```

`partition_root` and `partition_temp` appear only when the host reported them. `computeCapabilities` appears when the host has reported it.

### Field meanings that are easy to code wrong

- `cpu.free`, `cpu.used`, `cpu.total` are **logical CPU counts**, from the 5-minute load average, refreshed about every 60s. `cpu.unit` is the string `"%"` but the numbers are cores. Idle percent is `free / total`. Status: `CRITICAL` below 20% idle, `WARNING` below 30% idle.
- `memory.used` and `memory.total` are reported GB. `memory.free` is headroom after projected allocations and a **32 GB reserve**, floored at 0. It is not `total - used`.
- When swap is present, `memory.status` follows `oversubscribePct` (swap used as a percent of real RAM): `OK` at or under 10, `WARNING` above 10, `CRITICAL` above 40. That replaces the RAM-headroom status. `combinedPct` is (RAM used + swap used) / (RAM total + swap total).
- `storage.used` and `storage.total` are raw GB. `storage.free` is host-reported free GB (already net of the host reserve) plus projected allocation. If that sum is under 64 GB, `free` is **0**. Status: `CRITICAL` under 100 GB free, `WARNING` under 500 GB free. For byte counts use `storage.vmhstorage.getall`.
- `trafficInbound` / `trafficOutbound` are average Mbit/s since the previous ~60s sample. `total` is configured link speed, often 1000. `CRITICAL` under 100 Mbit/s free, `WARNING` under 200.
- `vmCount.total` is a planning soft cap of **80**, not a physical or scheduler limit. `WARNING` at 70 used, `CRITICAL` at 80.
- `partition_*.total` is a **30 GB display cap**, not the filesystem size. Use `free`. `WARNING` under 3 GB, `CRITICAL` under 1 GB.
- `outOfDate` is true when the check-in is older than 20 minutes. Metric columns can lag the heartbeat by a short queue delay; that does not matter at a 300s poll.
- `svcCodes`: `DHCPOK`/`DHCPFAIL`, `NICSOK`/`NICOK`/`NIC FAIL`, `DISKOK`/`DISKWARN`/`DISKFAIL`. `svcInfo` is `FAIL`, `WARN`, or `N/A`. NIC counts are omitted until the host has reported them.
- `computeCapabilities` refreshes lightly about every 300s and heavily about every 900s. `poolsStale` inside it means pool sizes came from storage inventory older than 900s.

## device.vmhost.get

REST: `GET /devices/vmhost`

```json
{"cmd":"device.vmhost.get","groupby":"dcname"}
```

Optional `customerid` (integer). Optional `groupby`: `country` or `dcname`. Omitted `groupby` returns a flat `vmhosts` array.

Rows use database column names: `DeviceID`, `DeviceName`, `DeviceDCID`, `DCCode`, `DCName`, `DCCountryCode`, `CountryName`, `DeviceStatus`, port speeds. There is no CPU or disk in this call. Use `DeviceID` as `vmhostDeviceId` / `deviceId` on the other commands.

## storage.vmhstorage.getall

```json
{"cmd":"storage.vmhstorage.getall"}
```

`storage.vmhstorage.get` with `{"deviceId":12345}` is the single-host form and includes the raw inventory.

List fields per host: `deviceId`, `deviceName`, `dcCode`, `dcName`, `totalBytes`, `usedBytes`, `freeBytes`, `logicalVolumeCount`, `replicatedVolumeCount`, `volumeGroups`, `observedAt` (unix seconds), `stale` (true when `observedAt` is older than 900s), `garbageCollectionBytes`, `storageCapabilities`. `storageCapabilities.ioEngines[].pool` has `capacityBytes`, `usedBytes`, `freeBytes`, `committedBytes` when the host reported an io-engine.

The host collects this every 300s. `storage.free` on the snapshot is the fleet headline. These byte fields are what you use to decide if a pool can take another volume.

## device.vmhost.vms.get

```json
{"cmd":"device.vmhost.vms.get","vmhostDeviceId":12345,"role":"ANY"}
```

`vmhostDeviceId` is required. `role` is `ANY` (default), `PRIMARY`, or `SECONDARY`.

Top-level: `vmhost`, `matches`, `vms`.

| Field | Meaning |
| --- | --- |
| `hostCpuSharePercent` | Share of CPU activity among active VMs on this host. Active VMs sum to about 100. `0` if the VM is inactive. `null` if there is no sample. |
| `memPct` | Guest RAM used, percent, from inside the VM. `null` if the guest agent has not reported. |
| `memoryGbAllocated` | RAM allocated on the device record. Use this when `memPct` is null. |
| `oversubscribePct` | Guest swap used as a percent of guest RAM. |
| `swapUsedKb`, `swapTotalKb`, `ramTotalKb` | Guest agent sample. |
| `storageTotalBytes` | Sum of mounted volumes, or the device storage figure when there are no mounts. |
| `lastGuestMetricTs` | Unix time of the latest guest memory sample. Ignore `memPct` when this is old. |
| `deviceStatus` | `ACTIVE` or `INACTIVE`. |

Hypervisor CPU share updates about every 60s. Guest percentages update when the guest agent reports, which is not every minute.

## monitoring.metrics.get

Latest guest sample for **one VM** (not the VM host). Reads a small latest-value cache, not RRD.

```json
{"cmd":"monitoring.metrics.get","deviceid":67890}
```

The parameter name is `deviceid` (lowercase).

- `cpu`: percent. Prefers hypervisor `H_CPU_USAGE_PCT`, else guest `G_CPU_USAGE_PCT`. `source` says which. `null` if neither exists. Includes `timestamp`.
- `memory`: guest RAM percent plus `ramUsedKb`, `ramTotalKb`, `swapUsedKb`, `swapTotalKb`, `oversubscribePct`, `combinedPct` when present. `timestamp` is the newest of those keys.
- `disk`: array of partitions with `mount_id`, `usage_pct`, `size_kb`, `used_kb`, `avail_kb`, `timestamp`.

## monitoring.data.get

RRD aggregate. Slow. Not a poll.

```json
{"cmd":"monitoring.data.get","deviceid":67890,"snmpid":"VMCPUSTATS","fromtime":1731000000,"totime":1731086400}
```

`deviceid` and `snmpid` are required. `fromtime` and `totime` are unix seconds. Default window is the last hour. There is no interval argument. The server picks the table from the window length:

| Window | Table | Point spacing | Retention |
| --- | --- | --- | --- |
| under 8 hours | 1-minute samples | 2 minutes | about 12 hours |
| 8 hours to 48 hours | 5-minute averages | 12 minutes | 14 days |
| over 48 hours | 30-minute averages | 30 minutes | 3 months |

Exceptions: `G_CPU` and `G_MEM` are read from the 5-minute table even for a short window. `G_NET` and `G_PROCESSES` are read from the 30-minute table only. A 15-minute query on those series does not return 1-minute points.

Samples are written about once a minute, then rolled up. Pulling the 1-minute table more often than the rollup does not add planning resolution, and that table is the expensive one.

Points are `[timestamp_milliseconds, value]`. Rate series (jiffies, traffic, disk IO) are a per-second delta. Gauge series are an averaged level. A counter reset is a gap. Outbound traffic is **negative** so a chart can draw it below the axis.

| snmpid | On | Series |
| --- | --- | --- |
| `VMCPUSTATS` | VM | `CPUJIFFIES` (jiffies per second) |
| `VMMEMSTATS` | VM | `ALLOCATED`, `RESIDENT` (MB, gauges) |
| `VMIOSTATS` | VM | `READ`, `WRITE` (MB/s) |
| `VMIOSTATSDEEP_<drive>` | VM | per-drive IO, busy, queue. One drive per call. Heavier than `VMIOSTATS`. |
| `G_CPU` | VM guest agent | cores, load 1/5/15, usage percent. Separate series per key. |
| `G_MEM` | VM guest agent | RAM and swap, KB and percent. |
| `G_DISK` | VM guest agent | per-partition size, used, available, percent. |
| `PUBLICTRAFFIC` | device | public in/out, Mbit/s. Out is negative. |

You cannot request 1-minute data from last week. That table only holds about 12 hours.

## Errors

`code` is `FAULT` with a `message`. Typical causes: unknown device, missing `vmhostDeviceId` or `deviceid`, unknown `snmpid`, or the key lacks device, monitoring, or storage permission.
