Skip to content

Get a VPS

GET /api/v2/vps/{id}

Get one VPS with its status, power state, primary IP, operating system, resources, price, bandwidth use and tags. It has the fields of GET /api/v2/vps and a few more. hardware is the host CPU and the CPU type the operating system sees. Action gates such as actions.canRestart are on GET /api/v2/vps/{id}/details.

billing.isPayg is true for a Cloud VPS. Its billing.amount is then null. A pending or suspended VPS also has overdueInvoices, the unpaid invoices for this server. An active VPS over its bandwidth allowance has its open bandwidth invoice there. A suspended, terminated or cancelled VPS has suspendedAt. A terminated or cancelled one also has terminatedAt and backupRetention, which says whether its backups are still stored and until when. 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

Path parameters

idstringrequired
The VPS ID (vps_…).

Example

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

Responses

200 The VPS.

Response 200
{
"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": "Ubuntu 24.04 with Docker",
"operatingSystemSourceName": "Ubuntu 24.04",
"updatedAt": "2026-06-30T10:00:00.000Z"
},
"hardware": {
"cpuModel": "AMD EPYC 7R13",
"cpuVendor": "amd",
"guestCpuModel": "EPYC-Rome-v5"
},
"resources": {
"cpuCores": 2,
"memoryGb": 4,
"storageGb": 80
},
"billing": {
"amount": 99,
"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",
"guestAgentSetupUntil": null,
"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
}
}
Response fields
idstring
namestring
primaryIpstring or null
serviceStatusstring
One of active, suspended, terminated, pending, cancelled, expired, fraud, transferred_out, unknown.
powerStatestring or null
One of running, stopped, starting, stopping, paused, provisioning, error, unknown.
operatingSystemobject or null
customerMetadataobject
Your own display labels. They do not replace name or operatingSystem.
displayNamestring or null
Your own name for the VPS. Null when not set.
operatingSystemNamestring or null
Your own name for the operating system. Null when not set. Also null after the operating system has changed since you set it.
operatingSystemSourceNamestring or null
The operating system that was installed when you set operatingSystemName.
updatedAtstring or null
billingobject
amountnumber or null
The price per billing cycle, in the currency of the resource. Null when there is no fixed price, as for a Cloud VPS.
currencyCodestring
billingCyclestring or null
The billing cycle. A Cloud VPS also shows monthly. Use isPayg to tell it apart from a fixed-cycle VPS. One of monthly, quarterly, semiannually, annually, biennially, triennially, free.
isPaygboolean
True for a Cloud VPS, which is billed for what it uses. False for a fixed-cycle VPS. Other services normally return false.
periodYearsinteger or null
paidPeriodobject
The paid period of an active fixed-cycle VPS. Absent for a Cloud VPS, for a VPS that is not active and when no paid period can be shown.
entitledThroughDatestring or null
The last day of extra coverage granted on top of what was paid. Show it as “covered through”, not “paid through”. Null when there is none.
reviewHandledboolean
True when Hostup has already handled a needs_review status with a coverage decision. It does not mark any invoice paid or remove one.
decisionRevisioninteger
Version of the coverage decision, counted apart from revision. A higher value is newer. At least 0.
revisioninteger
Version of the paid period. A higher value is newer. At least 0.
refreshRevisioninteger
Refresh round of the paid period. When you merge two reads, compare it before revision. At least 0.
statusstring
verified: 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 null
The last paid day, inclusive, in Swedish time (Europe/Stockholm). It is not an invoice due date or a suspension date.
outstandingInvoiceDueDatestring or null
sourceInvoiceNumbersarray of string
observedAtstring or null
scheduledChangenull
A change waiting for the next renewal: a smaller plan, a smaller resource or a switch to Cloud VPS. The same shape as in GET /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.
resourcesobject
cpuCoresnumber
memoryGbnumber
storageGbnumber
bandwidthobject
usedGbnumber
limitGbnumber
inboundGbnumber
outboundGbnumber
hasOverageboolean
availabilityobject
availableboolean
reasonstring or null
tagsarray of string
pinnedboolean
createdAtstring or null
expiresAtstring or null
When the current billing period ends, as the service record has it. It is not proof of payment. Use paidPeriod.paidThroughDate for the last paid day. Null when not set.
pendingMaintenanceboolean
Present only when the list is called with include=pendingMaintenance.
pendingMaintenanceHasDeadlineboolean
Present only together with pendingMaintenance.
diskThrottleobject
Disk limit status of this VPS. active: false means it was checked and no disk limit is active.
activeboolean
True when a disk limit is active on this VPS.
limitedReadboolean
limitedWriteboolean
readDrpdnumber or null
Disk reads per disk per day, when reads triggered the limit.
writeDwpdnumber or null
Disk writes per disk per day, when writes triggered the limit.
diskSizeGbnumber or null
estimatedDailyReadGbnumber or null
estimatedDailyWriteGbnumber or null
totalReadLast7DaysGbnumber or null
Total read over the last 7 days, in GB. Null when the limit measured fewer days.
totalWriteLast7DaysGbnumber or null
Total written over the last 7 days, in GB. Null when the limit measured fewer days. A limit that follows an earlier one counts only the days after that one ended. The 24-hour rule counts one day.
limitReadMbpsnumber or null
limitWriteMbpsnumber or null
limitWriteIopsnumber or null
Write operations per second the disks are held to while the limit is active. Null when only MB/s is limited.
throttledAtstring or null
expiresAtstring or null
escalationLevelinteger
At least 0.
removableByCustomerboolean
False for the third write limit within 30 days. Support lifts that one after a review. DELETE /api/v2/vps/{id}/disk-throttle then answers 403 disk_throttle_requires_support. True otherwise, also when no limit is active.
cpuLimitobject
CPU load limit status of this VPS. active: false means it was checked and there is no limit. Absent when it could not be read.
activeboolean
True when a CPU limit is active on this VPS.
vcpusnumber or null
vCPUs of the VPS when the limit was set or last adjusted.
limitVcpusnumber or null
CPU time the VPS may use, in vCPUs (half of vcpus).
limitPercentnumber or null
The limit as a percentage of all vCPUs.
averageLoadPercentnumber or null
The average load that set the limit, as a percentage of all vCPUs.
measuredDaysnumber or null
Days the average covers. Usually 7. It is 1 when the load came back within 30 days of an earlier limit being lifted.
limitedAtstring or null
liftBelowLoadPercentnumber or null
The limit is lifted once the last 24 hours averaged under this percentage of all vCPUs.
guestAgentSetupUntilstring or null
Set for about two minutes after a new VPS was set up. Until then the software inside the VPS may still be starting. Null otherwise. Only on GET /api/v2/vps/{id}.
overdueInvoicesarray of object
Unpaid invoices for this VPS. Present on a pending or suspended VPS. On an active VPS over its bandwidth allowance, it holds the open bandwidth invoice. Only on GET /api/v2/vps/{id}.
idstring
Invoice ID (inv_…).
numberstring or null
Invoice number to show.
amountnumber
Amount still to pay, not the invoice total.
currencyCodestring
dueAtstring or null
daysOverdueinteger or null
Days past the due date. Null when not yet due.
matchesVpsboolean
True when an invoice line names this VPS. When no unpaid invoice names it, the list holds up to three of the account’s unpaid invoices that are due first. Their matchesVps is false.
hardwareobject
The host CPU and the CPU type the VPS sees. Present only on GET /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 null
The physical CPU of the host, for example AMD EPYC 7R13.
cpuVendorstring or null
The CPU maker, read from the model. One of amd, intel, other.
guestCpuModelstring or null
The CPU type the operating system inside the VPS reports, for example in lscpu. 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 null
When the VPS was suspended. Present only on GET /api/v2/vps/{id}, while the VPS is suspended, terminated or cancelled. Null when no date is recorded.
terminatedAtstring or null
When the VPS was terminated and deleted. Present only on GET /api/v2/vps/{id}, for a terminated or cancelled VPS. Null when no date is recorded.
backupRetentionobject
What happened to the backups after the VPS ended. Present only on GET /api/v2/vps/{id}, for a terminated or cancelled VPS.
statusstring
One of retained, deleted, none, unknown.
backupCountinteger or null
Backups still stored (retained) or removed after the VPS ended (deleted). 0 for none. Null when unknown.
latestBackupAtstring or null
When the newest backup of this VPS was taken.
deleteAfterstring or null
retained only. The earliest time the stored backups may be deleted automatically.
deletedAtstring or null
deleted only. When the last backup was removed.
deletionReasonstring or null
deleted 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.
reasonstring
The state in plain words, ready to show.

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 belongs to another account, or your account is not active (detail says which). The other VPS endpoints answer 404 vps_not_found for a VPS on another account, so treat this 403 as not found.
404No VPS with this ID (not_found). This endpoint answers not_found, not vps_not_found like the other VPS endpoints, so check for both codes.
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.