Skip to main content
GET
List Volumes

Authorizations

Authorization
string
header
required

A Fly API token with access to the requested organization or resource. Send it as Authorization: Bearer <Fly API token>.

Path Parameters

app_name
string
required

Fly App Name

Query Parameters

summary
boolean

Only return summary info about volumes (omit blocks, block size, etc)

cursor
string

Value of the fly-next-cursor response header from the previous page. Requires limit.

limit
integer

The number of volumes to fetch (must be between 1 and 1000). Providing a limit enables pagination. This limit is advisory; responses may be shorter, or even empty, even when more volumes remain.

Response

OK

attached_alloc_id
string

Always null.

Deprecated: volumes are no longer attached to Nomad allocations.

attached_machine_id
string

ID of the Machine the volume is attached to, or null if it is not attached.

auto_backup_enabled
boolean

Whether daily automatic snapshots are taken.

block_size
integer

Size of a filesystem block, in bytes. See blocks.

blocks
integer

Size of the volume's filesystem, in blocks of block_size bytes, as last reported by a Machine that mounted the volume. 0 if never reported, if the host could not be reached, or with summary=true.

blocks_avail
integer

Number of filesystem blocks available to unprivileged users. See blocks.

blocks_free
integer

Number of free filesystem blocks, including blocks reserved for the root user. See blocks.

bytes_total
integer

Size of the volume, in bytes. 0 if the host could not be reached or with summary=true.

bytes_used
integer

Bytes of storage the volume occupies on its host. Volumes are thinly provisioned, so this grows as blocks are written and does not shrink when files are deleted. It is not the filesystem's usage; use blocks and blocks_free for that. 0 if the host could not be reached or with summary=true.

created_at
string

When the volume was created.

encrypted
boolean

Whether the volume is encrypted at rest.

fstype
string

Filesystem the volume was formatted with: ext4, or raw for an unformatted block device.

host_features
string[]

Features of the volume's host. Only returned when the request sets the fly-include-host-features: true header.

host_status
enum<string>

Whether Fly.io could reach the volume's host: ok if it could, unreachable or unknown if it could not, in which case host-reported fields are missing.

Available options:
ok,
unknown,
unreachable
id
string

Unique ID of the volume, such as vol_1234567890abcdef.

name
string

Name of the volume. Several volumes of an app can share a name.

region
string

Code of the region the volume is in.

required_host_features
string[]

Host features the volume's host was required to have; see compute.required_host_features in the create request.

size_gb
integer

Size of the volume, in GiB.

snapshot_retention
integer

Number of days snapshots of the volume are kept.

state
string

State of the volume, such as creating, created, extending, restoring, hydrating, scheduling_destroy, pending_destroy, destroying, destroyed, or failed.

type
enum<string>

Kind of volume: local for regular volumes, or cache for volumes that hold disposable data and support neither snapshots nor restores.

Available options:
local,
cache
zone
string

Identifies the host the volume is on. Volumes with different zones are on different hosts.