Skip to content

Get the disks and filesystems of a VPS

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

Returns the disks of a VPS with their size and use, the filesystems mounted inside it and the read and write totals. Each disk has gates that say whether it can be removed (canDetach), resized (canResize) or grown inside the VPS (canExpand). Use the disk id with POST /api/v2/vps/{id}/actions/resize-disk and DELETE /api/v2/vps/{id}/disks/{diskName}. Used space and filesystems come from the guest agent. While the VPS is stopped or has no guest agent, filesystems is empty and used space is 0. Sizes are in GB of 1024³ bytes. The VPS service must be active.

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

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Example

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

Responses

200 The disks, filesystems and disk gates of the VPS.

Response 200
{
"disks": [
{
"id": "vpsdisk_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "scsi0",
"type": "SCSI",
"device": "/dev/scsi0",
"guestDevice": "/dev/sda",
"isCdrom": false,
"bootOrder": 1,
"capacity": {
"totalGb": 80,
"usedGb": 24.2,
"freeGb": 55.8,
"usagePercent": 30.25
},
"io": {
"readGb": 120.5,
"writeGb": 64.2,
"readOperations": 102400,
"writeOperations": 51200
},
"actions": {
"canDetach": {
"allowed": false,
"reason": "Cannot detach root disk."
},
"canResize": {
"allowed": false,
"reason": "To expand your main disk, use Billing -> Add Resources."
},
"canExpand": {
"allowed": true,
"reason": null
}
}
}
],
"filesystems": [
{
"mountpoint": "/",
"type": "ext4",
"name": "rootfs",
"devices": [
"/dev/sda1"
],
"capacity": {
"totalGb": 78,
"usedGb": 24.2,
"freeGb": 53.8,
"usagePercent": 31.03
}
}
],
"blockStats": {
"totalReadGb": 120.5,
"totalWriteGb": 64.2
},
"guestAgentAvailable": true,
"vmNotRunning": false
}
Response fields
disksarray of object
The disks attached to the VPS, CD-ROM drives included.
idstring or null
Disk ID (vpsdisk_…). Use it as diskId to resize the disk.
namestring or null
Virtual slot of the disk, for example scsi0.
typestring or null
Bus type of the slot, for example SCSI.
devicestring or null
The slot written as a path. It is not the device name inside the VPS. See guestDevice.
guestDevicestring or null
Device name of the disk inside the VPS, for example /dev/sdb. It can differ from the slot in name. A CD-ROM drive takes a slot but no disk letter. The disk on scsi2 is then often /dev/sdb. Read from the guest agent when the disk holds a mounted filesystem. Otherwise worked out from the order of the attached disks. Null for CD-ROM drives and when no Linux device name applies.
isCdromboolean
True for a CD-ROM drive with an ISO image.
bootOrdernumber or null
Boot position. 1 is the main disk.
capacityobject
Size and use of the disk in GB. Use is 0 without the guest agent.
totalGbnumber
Disk size.
usedGbnumber
Space used by the filesystem on the disk.
freeGbnumber
Disk size minus used space.
usagePercentnumber
Used space as a percentage of the disk size.
ioobject
Data read from and written to the disk.
readGbnumber
Data read, in GB.
writeGbnumber
Data written, in GB.
readOperationsnumber
Number of read operations.
writeOperationsnumber
Number of write operations.
actionsobject
What can be done with this disk now.
canDetachobject
Whether the disk can be removed. Never for the main disk.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canResizeobject
Whether the disk can be made larger with POST /api/v2/vps/{id}/actions/resize-disk. On a VPS that is not a Cloud VPS, the main disk grows with the storageGb option on POST /api/v2/vps/{id}/actions/config instead.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canExpandobject
Whether the partition and filesystem can be grown inside the VPS after a resize. Needs a running VPS with the guest agent. Always false for a CD-ROM drive.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
filesystemsarray of object
Filesystems mounted inside the VPS. Empty without the guest agent.
mountpointstring or null
Where the filesystem is mounted.
typestring or null
Filesystem type.
namestring or null
Name the guest agent reports for the filesystem.
devicesarray of string
Devices the filesystem is on.
capacityobject
Size and use of the filesystem in GB.
totalGbnumber
usedGbnumber
freeGbnumber
usagePercentnumber
blockStatsobject
Read and write totals for all disks together.
totalReadGbnumber
Data read from all disks, in GB.
totalWriteGbnumber
Data written to all disks, in GB.
guestAgentAvailableboolean
True when the guest agent answered.
vmNotRunningboolean
True when the VPS is stopped.

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.