Get usage metrics of a VPS
GET /api/v2/vps/{id}/metrics
Returns CPU, memory, disk and network use of a VPS over a period, for graphs. Choose the period with timeframe. The VPS service must be active. A suspended or ended VPS returns 403 forbidden. samples holds the data points. summary has averages, peaks and totals in GB. totals has the exact bytes moved in the period. These totals cover only the chosen period. Monthly bandwidth use is on GET /api/v2/vps/{id}/bandwidth. diskDailyAverage always covers the last 7 days. When telemetry.available is false the data could not be collected. Empty samples then do not mean zero use. Rates use binary units (1 KB/s is 1024 bytes a second). GB totals are decimal (10⁹ bytes).
Authentication: An API key with the scope read:services. About keys and scopes
Request
Path parameters
idstringrequiredvps_…).Query parameters
timeframestringhour: the last hour, one sample a minute. day: the last 24 hours, one every 15 minutes. week: the last 7 days, one an hour. month: the last 30 days, one every 6 hours. year: the last 365 days, one a day. Default hour. 1h, 24h, 1d, 7d, 30d and 1y are accepted too. Another value answers 400 invalid_request. window.aggregationWindowSeconds in the response gives the spacing you got. One of hour, day, week, month, year. Default "hour".Example
curl "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/metrics" \ -H "Authorization: Bearer $HOSTUP_API_KEY"Responses
200 Usage metrics for the period.
{ "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3", "timeframe": "hour", "samples": [ { "recordedAt": "2026-11-02T11:59:00.000Z", "cpuUsagePercent": 11.8, "memoryUsagePercent": 42.1, "diskReadMbPerSecond": 0.95, "diskWriteMbPerSecond": 0.48, "networkInboundKbPerSecond": 2010, "networkOutboundKbPerSecond": 4050 }, { "recordedAt": "2026-11-02T12:00:00.000Z", "cpuUsagePercent": 12.5, "memoryUsagePercent": 42.5, "diskReadMbPerSecond": 1.05, "diskWriteMbPerSecond": 0.52, "networkInboundKbPerSecond": 2048, "networkOutboundKbPerSecond": 4096 } ], "totals": { "network": { "inboundBytes": 7549747200, "outboundBytes": 15099494400, "source": "counters" }, "disk": { "readBytes": 805306368, "writeBytes": 450971566, "source": "counters" } }, "diskDailyAverage": { "basisDays": 7, "readBytesPerDay": 11504566272, "writeBytesPerDay": 6442450944 }, "window": { "startAt": "2026-11-02T11:59:00.000Z", "endAt": "2026-11-02T12:00:00.000Z", "sampleCount": 2, "aggregationWindowSeconds": 60 }, "telemetry": { "available": true, "reason": null }, "summary": { "avgDiskReadMbPerSecond": 0.8, "avgDiskWriteMbPerSecond": 0.4, "peakDiskReadMbPerSecond": 2.1, "peakDiskWriteMbPerSecond": 1.3, "totalDiskReadGb": 0.81, "totalDiskWriteGb": 0.45, "totalNetworkInboundGb": 7.55, "totalNetworkOutboundGb": 15.1, "avgNetworkInboundKbPerSecond": 2048, "avgNetworkOutboundKbPerSecond": 4096, "peakNetworkInboundKbPerSecond": 8192, "peakNetworkOutboundKbPerSecond": 16384 }}Response fields
idstringtimeframestringhour, day, week, month, year.samplesarray of objectrecordedAtstringcpuUsagePercentnumbermemoryUsagePercentnumberdiskReadMbPerSecondnumberdiskWriteMbPerSecondnumbernetworkInboundKbPerSecondnumbernetworkOutboundKbPerSecondnumbersummaryobjecttotals. null means the value is unavailable for the window. Zero is always a measured zero.avgDiskReadMbPerSecondnumber or nullavgDiskWriteMbPerSecondnumber or nullpeakDiskReadMbPerSecondnumber or nullpeakDiskWriteMbPerSecondnumber or nulltotalDiskReadGbnumber or nulltotalDiskWriteGbnumber or nulltotalNetworkInboundGbnumber or nulltotalNetworkOutboundGbnumber or nullavgNetworkInboundKbPerSecondnumber or nullavgNetworkOutboundKbPerSecondnumber or nullpeakNetworkInboundKbPerSecondnumber or nullpeakNetworkOutboundKbPerSecondnumber or nulltotalsobjectsource: "counters": read from cumulative traffic counters. These are exact, do not depend on the chart resolution and survive restarts. source: "estimated": added up from the sampled rates. null bytes mean unknown, never zero. These totals cover only the window. They are separate from the monthly bandwidth allowance.networkobjectinboundBytesinteger or nulloutboundBytesinteger or nullsourcestring or nullcounters, estimated.diskobjectreadBytesinteger or nullwriteBytesinteger or nullsourcestring or nullcounters, estimated.diskDailyAverageobjectbasisDays days divided by that number of days. The disk fair-use check uses the same measure. It does not follow timeframe. null means unknown for the period, never zero.basisDaysintegerreadBytesPerDayinteger or nullwriteBytesPerDayinteger or nullwindowobjectstartAt and endAt are the first and last sample times. They are null when there are no samples. aggregationWindowSeconds is the resolution of the samples. It is null when unknown.startAtstring or nullendAtstring or nullsampleCountintegeraggregationWindowSecondsinteger or nulltelemetryobjectavailable is false the list of samples is empty. Treat that as no data, not as zero use.availablebooleanreasonstring or nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | forbidden. With requiredScopes in the body, the API key lacks a scope. Without it, the VPS is not active, for example suspended or terminated. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |