List VPS instances
GET /api/v2/vps
Lists the VPS on your account, both fixed-period VPS and Cloud VPS. Active, pending and suspended VPS are included. Ended ones are not. Each item has the VPS ID (vps_…), name, status, power state, primary IP, operating system, resources, price, bandwidth use and tags. billing.isPayg is true for a Cloud VPS. Its billing.amount is then null. Filter with primaryIp or name to find one VPS. Action gates such as actions.canRestart are not on the list. Read them on GET /api/v2/vps/{id}/details. scheduledChange is set while a downgrade or a switch to Cloud VPS waits for the next renewal. Until then billing shows the price of the running period.
Authentication: An API key with the scope read:services. About keys and scopes
Request
Query parameters
limitinteger20. 1 to 100.cursorstringnextCursor from the previous page. If the last VPS on that page has ended since, the call starts again at the first page. Skip the IDs you already have.includestringpendingMaintenance to add pendingMaintenance (maintenance changes are pending) and pendingMaintenanceHasDeadline (one of them has a deadline) to each VPS. Only the first 50 VPS on the account are checked. The others come back without these fields. One of pendingMaintenance.primaryIpstringvps_... ID of the VPS that has this address.namestringcustomerMetadata.displayName). Not case-sensitive.Example
curl "https://cloud.hostup.se/api/v2/vps" \ -H "Authorization: Bearer $HOSTUP_API_KEY"Responses
200 One page of VPS.
{ "data": [ { "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3", "name": "app-01", "primaryIp": "192.0.2.10", "serviceStatus": "active", "powerState": "running", "operatingSystem": { "displayName": "Debian 12", "family": "debian", "version": "12", "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", "expiresAt": "2026-05-27T00:00:00.000Z", "scheduledChange": null, "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, "limitWriteIops": null, "throttledAt": null, "expiresAt": null, "escalationLevel": 0, "removableByCustomer": true }, "cpuLimit": { "active": false, "vcpus": null, "limitVcpus": null, "limitPercent": null, "averageLoadPercent": null, "measuredDays": null, "limitedAt": null, "liftBelowLoadPercent": null } } ], "hasMore": false, "nextCursor": null}Response fields
dataarray of objectidstringnamestringprimaryIpstring or nullserviceStatusstringactive, suspended, terminated, pending, cancelled, expired, fraud, transferred_out, unknown.powerStatestring or nullrunning, stopped, starting, stopping, paused, provisioning, error, unknown.operatingSystemobject or nullcustomerMetadataobjectname or operatingSystem.displayNamestring or nulloperatingSystemNamestring or nulloperatingSystemSourceNamestring or nulloperatingSystemName.updatedAtstring or nullbillingobjectamountnumber or nullcurrencyCodestringbillingCyclestring or nullmonthly. Use isPayg to tell it apart from a fixed-cycle VPS. One of monthly, quarterly, semiannually, annually, biennially, triennially, free.isPaygbooleanperiodYearsinteger or nullpaidPeriodobjectentitledThroughDatestring or nullreviewHandledbooleanneeds_review status with a coverage decision. It does not mark any invoice paid or remove one.decisionRevisionintegerrevision. A higher value is newer. At least 0.revisionintegerrefreshRevisionintegerrevision. At least 0.statusstringverified: paidThroughDate is confirmed. Show it. refreshing: the period is being read again. paidThroughDate is the last confirmed date, or null. needs_review: the period could not be confirmed automatically and Hostup checks it. Do not show a date. unavailable: no paid period can be shown now. One of verified, refreshing, needs_review, unavailable.paidThroughDatestring or nulloutstandingInvoiceDueDatestring or nullsourceInvoiceNumbersarray of stringobservedAtstring or nullscheduledChangenullGET /api/v2/vps/{id}/actions/upgrade. billing stays the price of the running period. scheduledChange.target.billing is the price from effectiveAt. null when nothing is waiting. Absent when the state could not be read.resourcesobjectcpuCoresnumbermemoryGbnumberstorageGbnumberbandwidthobjectusedGbnumberlimitGbnumberinboundGbnumberoutboundGbnumberhasOveragebooleanavailabilityobjectavailablebooleanreasonstring or nulltagsarray of stringpinnedbooleancreatedAtstring or nullexpiresAtstring or nullpaidPeriod.paidThroughDate for the last paid day. Null when not set.pendingMaintenancebooleaninclude=pendingMaintenance.pendingMaintenanceHasDeadlinebooleanpendingMaintenance.diskThrottleobjectactive: false means it was checked and no disk limit is active.activebooleanlimitedReadbooleanlimitedWritebooleanreadDrpdnumber or nullwriteDwpdnumber or nulldiskSizeGbnumber or nullestimatedDailyReadGbnumber or nullestimatedDailyWriteGbnumber or nulltotalReadLast7DaysGbnumber or nulltotalWriteLast7DaysGbnumber or nulllimitReadMbpsnumber or nulllimitWriteMbpsnumber or nulllimitWriteIopsnumber or nullthrottledAtstring or nullexpiresAtstring or nullescalationLevelintegerremovableByCustomerbooleanDELETE /api/v2/vps/{id}/disk-throttle then answers 403 disk_throttle_requires_support. True otherwise, also when no limit is active.cpuLimitobjectactive: false means it was checked and there is no limit. Absent when it could not be read.activebooleanvcpusnumber or nulllimitVcpusnumber or nullvcpus).limitPercentnumber or nullaverageLoadPercentnumber or nullmeasuredDaysnumber or nulllimitedAtstring or nullliftBelowLoadPercentnumber or nullguestAgentSetupUntilstring or nullGET /api/v2/vps/{id}.overdueInvoicesarray of objectGET /api/v2/vps/{id}.idstringinv_…).numberstring or nullamountnumbercurrencyCodestringdueAtstring or nulldaysOverdueinteger or nullmatchesVpsbooleanmatchesVps is false.hardwareobjectGET /api/v2/vps/{id}, not on the list. A field is null when it cannot be read now, for example for a pending or terminated VPS. Null means unknown, not an error.cpuModelstring or nullAMD EPYC 7R13.cpuVendorstring or nullamd, intel, other.guestCpuModelstring or nulllscpu. It is a virtual CPU profile, not the physical chip: EPYC-Rome-v5 or EPYC-Milan on AMD hosts, Cascade Lake on Intel hosts. After a CPU type change the VPS keeps its old type until the next restart. The physical CPU is cpuModel.suspendedAtstring or nullGET /api/v2/vps/{id}, while the VPS is suspended, terminated or cancelled. Null when no date is recorded.terminatedAtstring or nullGET /api/v2/vps/{id}, for a terminated or cancelled VPS. Null when no date is recorded.backupRetentionobjectGET /api/v2/vps/{id}, for a terminated or cancelled VPS.statusstringretained, deleted, none, unknown.backupCountinteger or nullretained) or removed after the VPS ended (deleted). 0 for none. Null when unknown.latestBackupAtstring or nulldeleteAfterstring or nullretained only. The earliest time the stored backups may be deleted automatically.deletedAtstring or nulldeleted only. When the last backup was removed.deletionReasonstring or nulldeleted only. retention_elapsed: the retention period after termination ended. removed_by_staff: removed by Hostup support. Null when not recorded. One of retention_elapsed, removed_by_staff.reasonstringhasMorebooleannextCursorstring or nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_pagination_limit: limit is not a whole number from 1 to 100. invalid_cursor: cursor is malformed. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 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. |