Skip to content

List VPS backup schedules

GET /api/v2/vps/{id}/backup-schedules

Returns the backup schedule of a VPS with its backup settings, the 20 newest backups, its limits and the actions you can take. A VPS has at most one schedule. Use schedules[].id to delete it. limits.maxRetention is the highest retentionCount a schedule may use. Check actions.canCreate, actions.canUpdateSettings or actions.canDelete before the matching call. 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_…).

Example

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

Responses

200 The backup schedule, settings, recent backups, limits and action gates.

Response 200
{
"schedules": [
{
"id": "bks_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "Weekly backup",
"frequency": "weekly",
"time": "02:00",
"daySpecifier": "1",
"retentionCount": 5,
"enabled": true,
"lastRun": "2026-04-27T00:00:00.000Z",
"nextRun": "2026-05-04T00:00:00.000Z",
"status": null,
"lastRunStatus": "completed",
"lastRunAt": "2026-04-27T00:00:00.000Z"
}
],
"settings": {
"totalBackupLimit": 5,
"manualBackupsActive": 1,
"scheduledBackupsActive": 2,
"availableScheduledSlots": 2,
"autoDeleteOldest": true
},
"history": [
{
"backupType": "scheduled",
"status": "running",
"createdAt": "2026-04-27T00:00:00.000Z",
"updatedAt": "2026-04-27T00:41:00.000Z",
"note": "Weekly backup"
}
],
"limits": {
"maxSchedules": 1,
"totalBackups": 5,
"maxRetention": 5,
"currentSchedules": 1,
"manualBackupsActive": 1,
"scheduledBackupsActive": 2,
"availableScheduledSlots": 2
},
"actions": {
"canCreate": {
"allowed": false,
"reason": "A backup schedule already exists. Update or delete it before creating another."
},
"canUpdateSettings": {
"allowed": true,
"reason": null
},
"canDelete": {
"allowed": true,
"reason": null
}
}
}
Response fields
schedulesarray of object
idstring
Schedule ID (bks_…).
namestring
Label of the schedule.
frequencystring
How often it runs: daily, weekly or monthly. One of daily, weekly, monthly.
timestring or null
Time of day it runs, HH:MM in Europe/Stockholm time.
daySpecifierstring or null
Day of the week (0 is Sunday) for weekly. Day of the month for monthly. Null for daily.
retentionCountinteger
How many scheduled backups it keeps.
enabledboolean
Whether the schedule runs.
lastRunstring or null
When it last ran.
nextRunstring or null
When it runs next.
statusstring or null
Status of the schedule, when one is reported. Read lastRunStatus for the result of its last backup. One of completed, running, queued, failed, cancelled, unknown.
lastRunStatusstring or null
Result of the newest backup this schedule made: completed, failed or queued. Null when it has not run yet. One of completed, running, queued, failed, cancelled, unknown.
lastRunAtstring or null
When the newest backup of this schedule started. Null when it has not run yet.
settingsobject
totalBackupLimitinteger
Most backups kept for this VPS, manual and scheduled together.
manualBackupsActiveinteger
Manual backups stored now.
scheduledBackupsActiveinteger
Scheduled backups stored now.
availableScheduledSlotsinteger
Backups the schedule can still keep next to the manual ones.
autoDeleteOldestboolean
Whether the oldest scheduled backups are deleted when a new scheduled backup needs room.
historyarray of object
The 20 most recent backups of the VPS, manual and scheduled, newest first.
backupTypestring or null
scheduled or manual.
statusstring
State of the backup. Today a finished backup that is still stored shows running, not completed. A deleted backup shows unknown. queued is a backup still being made. failed is one that failed. For the result of a scheduled run, read schedules[].lastRunStatus. One of completed, running, queued, failed, cancelled, unknown.
createdAtstring or null
updatedAtstring or null
notestring or null
Label stored with the backup.
limitsobject
maxSchedulesinteger
Most schedules a VPS can have. Always 1.
totalBackupsinteger
Most backups kept for this VPS.
maxRetentioninteger
Highest retentionCount a schedule may use.
currentSchedulesinteger
Schedules the VPS has now.
manualBackupsActiveinteger
Manual backups stored now.
scheduledBackupsActiveinteger
Scheduled backups stored now.
availableScheduledSlotsinteger
Backups the schedule can still keep next to the manual ones.
actionsobject
canCreateobject
Whether POST /api/v2/vps/{id}/backup-schedules can create a schedule now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canUpdateSettingsobject
Whether PATCH /api/v2/vps/{id}/backup-schedules can change the settings now.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canDeleteobject
Whether the schedule can be deleted 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.
502Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists.