Skip to content

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

idstringrequired
The VPS ID (vps_…).

Query parameters

timeframestring
The period, counted back from now. hour: 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

GET /api/v2/vps/{id}/metrics
curl "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/metrics" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 Usage metrics for the period.

Response 200
{
"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
idstring
timeframestring
One of hour, day, week, month, year.
samplesarray of object
recordedAtstring
cpuUsagePercentnumber
memoryUsagePercentnumber
diskReadMbPerSecondnumber
diskWriteMbPerSecondnumber
networkInboundKbPerSecondnumber
networkOutboundKbPerSecondnumber
summaryobject
Totals and averages over the window. Averages are weighted by time over the real sample intervals. Totals are in decimal GB (1 GB = 10^9 bytes), from the same byte counts as totals. null means the value is unavailable for the window. Zero is always a measured zero.
avgDiskReadMbPerSecondnumber or null
avgDiskWriteMbPerSecondnumber or null
peakDiskReadMbPerSecondnumber or null
peakDiskWriteMbPerSecondnumber or null
totalDiskReadGbnumber or null
totalDiskWriteGbnumber or null
totalNetworkInboundGbnumber or null
totalNetworkOutboundGbnumber or null
avgNetworkInboundKbPerSecondnumber or null
avgNetworkOutboundKbPerSecondnumber or null
peakNetworkInboundKbPerSecondnumber or null
peakNetworkOutboundKbPerSecondnumber or null
totalsobject
Exact transfer in the selected window, in bytes. source: "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.
networkobject
inboundBytesinteger or null
outboundBytesinteger or null
sourcestring or null
One of counters, estimated.
diskobject
readBytesinteger or null
writeBytesinteger or null
sourcestring or null
One of counters, estimated.
diskDailyAverageobject
Average disk reads and writes per day: the bytes over the last basisDays 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.
basisDaysinteger
readBytesPerDayinteger or null
writeBytesPerDayinteger or null
windowobject
The time the samples really cover. startAt 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 null
endAtstring or null
sampleCountinteger
aggregationWindowSecondsinteger or null
telemetryobject
Whether metrics could be collected. When available is false the list of samples is empty. Treat that as no data, not as zero use.
availableboolean
reasonstring or null

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403forbidden. With requiredScopes in the body, the API key lacks a scope. Without it, the VPS is not active, for example suspended or terminated.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.