Skip to content
HostupDevelopers
GuidesAPI referenceSupport

Get VPS bandwidth usage for this period

GET /api/v2/vps/{id}/bandwidth

Shows how much bandwidth a VPS has used in the current allowance period and when the traffic happened. allowance holds the same numbers as bandwidth on GET /api/v2/vps/{id}. breakdown.days splits the traffic by calendar day in Europe/Stockholm time. breakdown.peakHour is the busiest hour. Traffic is measured on the VPS’s network interface. A single large transfer shows up as one busy day or hour. When breakdown.available is false, the traffic could not be measured. It does not mean there was no traffic. This also works for a suspended VPS and for a VPS over its allowance.

Authentication: An API key with the scope read:vm. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Example

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

Responses

200 Bandwidth use in the current period.

Response 200
{
  "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "period": {
    "startAt": "2026-08-25T22:00:00.000Z",
    "endAt": "2026-09-25T22:00:00.000Z",
    "timezone": "Europe/Stockholm"
  },
  "allowance": {
    "usedGb": 123.25,
    "limitGb": 2048,
    "inboundGb": 65.13,
    "outboundGb": 58.12,
    "usagePercent": 6.02,
    "hasOverage": false
  },
  "breakdown": {
    "available": true,
    "reason": null,
    "source": "counters",
    "window": {
      "startAt": "2026-08-27T15:00:00.000Z",
      "endAt": "2026-08-31T12:00:00.000Z"
    },
    "days": [
      {
        "date": "2026-08-26",
        "inboundGb": 0,
        "outboundGb": 0
      },
      {
        "date": "2026-08-27",
        "inboundGb": 65.05,
        "outboundGb": 57.61
      },
      {
        "date": "2026-08-28",
        "inboundGb": 0.2,
        "outboundGb": 0.1
      },
      {
        "date": "2026-08-29",
        "inboundGb": 0.1,
        "outboundGb": 0.05
      },
      {
        "date": "2026-08-30",
        "inboundGb": 0,
        "outboundGb": 0
      },
      {
        "date": "2026-08-31",
        "inboundGb": 0.02,
        "outboundGb": 0.01
      }
    ],
    "hasHourlyResolution": true,
    "hours": [
      {
        "startAt": "2026-08-27T15:00:00.000Z",
        "inboundGb": 0.05,
        "outboundGb": 0.01
      },
      {
        "startAt": "2026-08-27T16:00:00.000Z",
        "inboundGb": 65,
        "outboundGb": 57.6
      },
      {
        "startAt": "2026-08-27T23:00:00.000Z",
        "inboundGb": 0.2,
        "outboundGb": 0.1
      },
      {
        "startAt": "2026-08-29T10:00:00.000Z",
        "inboundGb": 0.1,
        "outboundGb": 0.05
      },
      {
        "startAt": "2026-08-31T09:00:00.000Z",
        "inboundGb": 0.02,
        "outboundGb": 0.01
      }
    ],
    "peakHour": {
      "startAt": "2026-08-27T16:00:00.000Z",
      "inboundGb": 65,
      "outboundGb": 57.6
    }
  }
}
Response fields
idstring
The VPS ID.
periodobject or null
The current allowance period. Null when the VPS has no billing date to count from.
allowanceobject
Use in this period. The same numbers as bandwidth on GET /api/v2/vps/{id}.
usedGbnumber
Traffic counted against the allowance, in GB.
limitGbnumber
The allowance for the period, in GB.
inboundGbnumber
Incoming traffic, in GB.
outboundGbnumber
Outgoing traffic, in GB.
usagePercentnumber
Share of the allowance used, in percent.
hasOverageboolean
True when the VPS has used more than its allowance.
breakdownobject
availableboolean
False when the traffic could not be measured. days is then empty and peakHour null.
reasonstring or null
Why the breakdown is missing when available is false. Null otherwise.
sourcestring or null
counters for exact interface counters. estimated for amounts worked out from sampled traffic rates. Null when unavailable. The same values as totals.source on GET /api/v2/vps/{id}/metrics. One of counters, estimated.
windowobject
The first and last moment in the period with traffic data. Both null when unavailable.
startAtstring or null
endAtstring or null
daysarray of object
One entry per Europe/Stockholm calendar day from the start of the period through today, oldest first. A day with no traffic is a real zero.
datestring
inboundGbnumber
outboundGbnumber
hasHourlyResolutionboolean
Whether traffic can be placed in single hours. False for an estimated breakdown with samples further apart than an hour. hours is then empty and peakHour null.
hoursarray of object
Every hour in the period with measured traffic, oldest first. Hours not listed had none. Empty when hasHourlyResolution is false.
startAtstring
Start of the 60-minute window (a whole hour).
inboundGbnumber
outboundGbnumber
peakHourobject or null
The hour with the most traffic in this period. Null when no traffic was measured or when hasHourlyResolution is false.

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. The caller lacks a required scope or does not own the resource.
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.

This page as MarkdownOpenAPI spec