Skip to content

List VPS backups

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

Lists the backups of a VPS with the backup quota and the actions you can take now. Use a backup’s id as {backupId} to restore or delete it. Check actions.canCreateBackup before you create a backup. Check actions.canRestore and the backup’s own actions.canRestore before you restore one. A backup without disk images holds only the server configuration and cannot restore a server. When listing.status is unavailable, the list could not be read right now. It is then empty and the gates are closed. It does not mean the backups are gone. Backups are offsite copies kept longer than snapshots. They can take longer to create and restore.

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

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Query parameters

includeDiskCoverageboolean
Set to true to add diskSelection: which of the current disks backups include, read live from the server. Only the exact value true turns it on. Default false. Default false.

Example

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

Responses

200 The backups, the quota and the action gates.

Response 200
{
"backups": [
{
"id": "bkp_01hxa3b4c5d6e7f8g9h0j1k2m3",
"displayId": "2026-10-27T10:00:00.000Z (2026-10-27T10:00:00Z)",
"storageKey": "2026-10-27T10:00:00Z",
"createdAt": "2026-10-27T10:00:00.000Z",
"sizeGb": 12,
"minimumRestoreStorageGb": 50,
"minimumRestoreStorageSource": "backup",
"actions": {
"canRestore": {
"allowed": true,
"reason": null
}
},
"diskImageInventory": {
"source": "pbs_manifest",
"disks": [
{
"slot": "scsi0",
"sizeGb": 50
}
]
},
"backupType": "manual",
"note": "Before upgrade"
}
],
"listing": {
"status": "complete",
"reason": null
},
"quotaInfo": {
"used": 1,
"limit": 3,
"remaining": 2
},
"actions": {
"canCreateBackup": {
"allowed": true,
"reason": null
},
"canRestore": {
"allowed": true,
"reason": null
},
"canRestoreToNewCloudVm": {
"allowed": true,
"reason": null
},
"canRestoreToNewRegularVps": {
"allowed": true,
"reason": null
},
"canRestoreFromAnotherVps": {
"allowed": true,
"reason": null
}
}
}
Response fields
diskSelectionobject
Present only with includeDiskCoverage=true. Which current disks backups include.
statusstring
unavailable when the disks could not be read. That is not an empty disk list. One of confirmed, unavailable.
disksarray of object
slotstring
Disk slot on the VPS.
sizeGbnumber or null
Disk size in GB.
includedboolean
Whether backups include this disk.
reasonstring
Why the disk is or is not included. One of attached, backup_disabled, detached, cdrom.
backupsarray of object
The backups of this VPS.
idstring
displayIdstring
Creation time and storageKey together, for display. Use id to refer to the backup.
storageKeystring
The backup’s name in storage, for display.
createdAtstring or null
When the backup was made. Null when not known.
sizeGbinteger
Size of the backup, rounded to whole GB. Do not use it to size a restore target. Use minimumRestoreStorageGb.
minimumRestoreStorageGbinteger
The smallest disk, in GB, a VPS needs to take this backup. Use it when you restore to a new or another VPS. 0 for a backup with no disk data.
minimumRestoreStorageSourcestring
backup: read from the backup itself. estimate: worked out from the VPS disk size or the backup size. An estimate can be off when the disk was resized after the backup. The restore checks again before it writes anything. One of backup, estimate.
backupTypestring
scheduled: made by a backup schedule. manual: any other backup, such as one started through the API or the client area. One of manual, scheduled.
notestring or null
The label stored with the backup. A manual backup made without a note has Manual backup. Null when there is none.
actionsobject
Whether this backup can be restored. A backup with configuration only and no disk data has canRestore.allowed: false, even when the VPS allows restores.
canRestoreobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
diskImageInventoryobject
The disk images stored in this backup, read from the backup itself. source is pbs_manifest when the list is complete, partial when disks may be missing from it and unavailable when it could not be read. The current disks of the VPS say nothing about what an older backup holds. A disk missing from a partial or unavailable list may still be in the backup.
sourcestring
One of pbs_manifest, partial, unavailable.
disksarray of object
slotstring
sizeGbnumber or null
Size of the disk image in GiB, when recorded.
listingobject
Whether the backup list could be read.
statusstring
unavailable when the list could not be read right now. backups is then empty. One of complete, unavailable.
reasonstring or null
Text to show when status is unavailable.
quotaInfoobject
How many backup slots are used and left.
usedinteger or null
Backups stored now. Null while the list is unavailable.
limitinteger or null
Most backups this VPS can keep. Null when no limit is known.
remaininginteger or null
Free backup slots. Null when unknown.
actionsobject
canCreateBackupobject
Whether POST /api/v2/vps/{id}/backups can start a backup now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canRestoreobject
Whether a backup can be restored onto this VPS now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canRestoreToNewCloudVmobject
Whether a backup can be restored to a new Cloud VPS now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canRestoreToNewRegularVpsobject
Whether a backup can be restored to a new fixed-plan VPS now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canRestoreFromAnotherVpsobject
Whether a backup of another VPS can be restored onto this VPS now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.

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.