List VPS instances

GET /api/v2/vps

Return existing VPS instances with public IDs, canonical service/power status, billing, resources, primary IP, operating system, bandwidth, availability, tags, and pin state.

Requires read:vm.

Note for API keys: the account-wide inventory lookup behind this collection also needs the broader read:services grant — a key holding only read:vm receives an empty list, so mint keys for this collection with read:services as well.

Use primaryIp=192.0.2.10 to find the public vps_... ID when the caller only knows an IP address; do not pass IP addresses or hostnames as {id} to detail/action routes.

Use data[].id from this endpoint as the {id} path parameter for VPS details, power actions, backups, snapshots, networking, and console calls.

This inventory can include both regular fixed-cycle VPS and pay-as-you-go Cloud VPS after deployment; inspect billing.isPayg instead of guessing from the name.

billing.isPayg: false means a fixed-cycle VPS ordered from GET /api/v2/products/vps and POST /api/v2/orders; billing.isPayg: true means a PAYG Cloud VPS created from the Cloud VPS endpoints and billing.amount is null.

Disk throttle state is included by default as diskThrottle.

Action gates live on the richer detail/status endpoints, not on this list response.

VPS Services VM

Authentication

Required API scope: read:services

Authenticate with an API key in the Authorization: Bearer <token> header.

Context

Query Parameters

limit integer · min: 1 · max: 100 · default: 20

Page size from 1 to 100. Defaults to 20. Values outside that range are rejected with 400 invalid_pagination_limit.

cursor string

Opaque cursor from nextCursor for the next page.

include string · enum · Example: pendingMaintenance

Optional repeated include. Currently supports pendingMaintenance; call as ?include=pendingMaintenance to add pendingMaintenance and pendingMaintenanceHasDeadline to each item. Disk throttle state is included by default as diskThrottle.

pendingMaintenance
primaryIp string · Example: 192.0.2.10

Exact primary IP address to find. Use this to get the public vps_... ID for a VPS when the caller only knows its IP address.

name string · Example: app-01

Exact VPS display name to find. Matching is case-insensitive and returns the same paginated list shape.

Headers

Authorization Bearer <token>
Accept application/json

Responses

200 Cursor-paginated list.
data array<object>
data[].id string required · Example: vps_01hxa3b4c5d6e7f8g9h0j1k2m3
data[].name string required · Example: app-01
data[].primaryIp string · nullable required · Example: 192.0.2.10

Nullable: may be null when not applicable.

data[].serviceStatus string · enum required · Example: active
active
suspended
terminated
pending
cancelled
expired
fraud
unknown
data[].powerState string · nullable · enum required · Example: running

Nullable: may be null when not applicable.

running
stopped
starting
stopping
paused
provisioning
error
unknown
data[].operatingSystem object · nullable required · Example: {"displayName":"Ubuntu 24.04","family":"ubuntu","version":"24.04","variant":null}

Nullable: may be null when not applicable.

data[].customerMetadata object

Customer-owned display labels. These do not replace canonical name, hostname, or operatingSystem fields.

data[].customerMetadata.displayName string · nullable required · Example: Production DB

Nullable: may be null when not applicable.

data[].customerMetadata.operatingSystemName string · nullable required · Example: Debian 13

Nullable: may be null when not applicable.

data[].customerMetadata.operatingSystemSourceName string · nullable required · Example: Debian 12

Nullable: may be null when not applicable.

data[].customerMetadata.updatedAt string · nullable required · Example: 2026-06-30T10:00:00.000Z

Nullable: may be null when not applicable.

data[].billing object required
data[].billing.amount number · nullable required · Example: 199

Recurring fixed-cycle amount in the resource currency. Null when no fixed recurring amount applies, such as PAYG Cloud VPS billing.

data[].billing.currencyCode string required · Example: SEK
data[].billing.billingCycle string · nullable · enum required · Example: annually

Canonical billing cycle. VPS services with isPayg: true still report monthly for summary display; use isPayg to distinguish PAYG Cloud VPS from fixed-cycle VPS.

monthly
quarterly
semiannually
annually
biennially
triennially
free
data[].billing.isPayg boolean required · Example: false

For VPS service/order billing, true means pay-as-you-go Cloud VPS and false means fixed-cycle/prepaid VPS. Non-VPS resources normally return false.

data[].billing.periodYears integer · nullable · Example: 1

Nullable: may be null when not applicable.

data[].resources object required
data[].resources.cpuCores number · Example: 2
data[].resources.memoryGb number · Example: 4
data[].resources.storageGb number · Example: 80
data[].bandwidth object required
data[].bandwidth.usedGb number required · Example: 12.5
data[].bandwidth.limitGb number required · Example: 1000
data[].bandwidth.inboundGb number required · Example: 4.2
data[].bandwidth.outboundGb number required · Example: 8.3
data[].bandwidth.hasOverage boolean required · Example: false
data[].availability object required
data[].availability.available boolean required · Example: true
data[].availability.reason string · nullable required · Example: null

Nullable: may be null when not applicable.

data[].tags array<string> required · Example: ["production"]
data[].pinned boolean required · Example: false
data[].createdAt string · nullable required · Example: 2026-04-27T12:00:00.000Z

Nullable: may be null when not applicable.

data[].pendingMaintenance boolean · Example: false

Only present when the list route is called with include=pendingMaintenance.

data[].pendingMaintenanceHasDeadline boolean · Example: false

Only present together with pendingMaintenance.

data[].overdueInvoices array<object>

Only present on single-detail routes when overdue invoices were queried.

data[].diskThrottle object required

Disk throttle status for this VPS. active:false means the API checked local throttle state and found no active disk limit.

data[].diskThrottle.active boolean required · Example: true

True when an active disk throttle exists for this VPS.

data[].diskThrottle.limitedRead boolean required · Example: false
data[].diskThrottle.limitedWrite boolean required · Example: true
data[].diskThrottle.readDrpd number · nullable required · Example: null

Disk reads per disk per day, when reads triggered the throttle.

data[].diskThrottle.writeDwpd number · nullable required · Example: 10.06

Disk writes per disk per day, when writes triggered the throttle.

data[].diskThrottle.diskSizeGb number · nullable required · Example: 100

Nullable: may be null when not applicable.

data[].diskThrottle.estimatedDailyReadGb number · nullable required · Example: null

Nullable: may be null when not applicable.

data[].diskThrottle.estimatedDailyWriteGb number · nullable required · Example: 1006

Nullable: may be null when not applicable.

data[].diskThrottle.totalReadLast7DaysGb number · nullable required · Example: null

Nullable: may be null when not applicable.

data[].diskThrottle.totalWriteLast7DaysGb number · nullable required · Example: 7042

Nullable: may be null when not applicable.

data[].diskThrottle.limitReadMbps number · nullable required · Example: null

Nullable: may be null when not applicable.

data[].diskThrottle.limitWriteMbps number · nullable required · Example: 1

Nullable: may be null when not applicable.

data[].diskThrottle.throttledAt string · nullable required · Example: 2026-06-17T14:00:09.000Z

Nullable: may be null when not applicable.

data[].diskThrottle.expiresAt string · nullable required · Example: 2026-06-18T14:00:09.000Z

Nullable: may be null when not applicable.

data[].diskThrottle.escalationLevel integer · min: 0 required · Example: 1
data[].hardware object

Host hardware info. Present on GET /api/v2/vps/{id} only (absent on the list read). Each field is null when the platform cannot resolve node placement right now (e.g. service pending) — null means "unknown", not an error.

data[].hardware.cpuModel string · nullable

Physical CPU model of the host node, e.g. "AMD EPYC 7R13".

data[].hardware.cpuVendor string · nullable · enum

CPU vendor family derived from the model.

amd
intel
other
hasMore boolean · Example: false
nextCursor string · nullable · Example: null

400 Invalid request. The response body is an RFC 7807 Problem Details document.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
401 Unauthorized. Authentication is required.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
403 Forbidden. The caller lacks a required scope or does not own the resource.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
404 Not found. The resource does not exist or is not owned by the caller.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
429 Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
500 Internal error. Retry later or contact support if the issue persists.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
GET https://cloud.hostup.se/api/v2/vps
For AI assistants
View as Markdown
cURL 
curl -X GET "https://cloud.hostup.se/api/v2/vps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
Response 
{
  "data": [
    {
      "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "name": "app-01",
      "primaryIp": "192.0.2.10",
      "serviceStatus": "active",
      "powerState": "running",
      "operatingSystem": {
        "displayName": "Ubuntu 24.04",
        "family": "ubuntu",
        "version": "24.04",
        "variant": null
      },
      "customerMetadata": {
        "displayName": "Production DB",
        "operatingSystemName": "Debian 13",
        "operatingSystemSourceName": "Debian 12",
        "updatedAt": "2026-06-30T10:00:00.000Z"
      },
      "resources": {
        "cpuCores": 2,
        "memoryGb": 4,
        "storageGb": 80
      },
      "billing": {
        "amount": 199,
        "currencyCode": "SEK",
        "billingCycle": "monthly",
        "isPayg": false
      },
      "bandwidth": {
        "usedGb": 12.5,
        "limitGb": 1000,
        "inboundGb": 4.2,
        "outboundGb": 8.3,
        "hasOverage": false
      },
      "availability": {
        "available": true,
        "reason": null
      },
      "tags": [
        "production"
      ],
      "pinned": false,
      "createdAt": "2026-04-27T12:00:00.000Z",
      "pendingMaintenance": false,
      "pendingMaintenanceHasDeadline": false,
      "diskThrottle": {
        "active": false,
        "limitedRead": false,
        "limitedWrite": false,
        "readDrpd": null,
        "writeDwpd": null,
        "diskSizeGb": null,
        "estimatedDailyReadGb": null,
        "estimatedDailyWriteGb": null,
        "totalReadLast7DaysGb": null,
        "totalWriteLast7DaysGb": null,
        "limitReadMbps": null,
        "limitWriteMbps": null,
        "throttledAt": null,
        "expiresAt": null,
        "escalationLevel": 0
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null
}