List VPS instances

Return existing VPS instances with public IDs, canonical service/power status, billing, resources, primary IP, operating system, bandwidth, availability, tags, and pin state. 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…

Read full description Hide full description

Return existing VPS instances with public IDs, canonical service/power status, billing, resources, primary IP, operating system, bandwidth, availability, tags, and pin state. 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. Action gates live on the richer detail/status endpoints, not on this list response.

VPS Services VM

Authentication

Required API scope: read:vm

Use Authorization: Bearer <token> for API keys. Dashboard sessions may also use hostup_session.

Context

Query Parameters

limit integer · min: 1 · max: 100

Maximum VPS instances to return in this page.

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.

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

Accept Example
Content-Type Example

Responses

200 Cursor-paginated list.
data array<object>
data[].id string required · Example: vps_01hxa3b4c5d6e7f8g9h0j1k2m3
data[].name string required · Example: app-01
data[].primaryIp stringnull required · Example: 192.0.2.10
data[].serviceStatus string · enum required · Example: active
active
suspended
terminated
pending
cancelled
expired
fraud
unknown
data[].powerState stringnull · enum required · Example: running
running
stopped
starting
stopping
paused
provisioning
error
unknown
data[].operatingSystem objectnull required · Example: {"displayName":"Ubuntu 24.04","family":"ubuntu","version":"24.04","variant":null}
data[].billing object required
data[].billing.amount number required · Example: 199
data[].billing.currencyCode string required · Example: SEK
data[].billing.billingCycle stringnull · 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 integernull · Example: 1
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 stringnull required · Example: null
data[].tags array<string> required · Example: ["production"]
data[].pinned boolean required · Example: false
data[].createdAt stringnull required · Example: 2026-04-27T12:00:00.000Z
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.

hasMore boolean · Example: false
nextCursor stringnull · 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
      },
      "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
    }
  ],
  "hasMore": false,
  "nextCursor": null
}