> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Volumes

You can use the Volumes resource to create and delete volumes. A Fly Volume is persistent storage for a Fly Machine. Learn more about [volumes](/volumes/).

<div className="rounded-xl bg-[#0d1526] border border-white/10 overflow-hidden not-prose">
  <div className="px-5 py-3 border-b border-white/10">
    <span className="text-white text-sm font-semibold">Endpoints</span>
  </div>

  <div className="px-5 py-4 flex flex-col gap-3">
    <a href="#list-all-the-volumes-in-an-app" className="flex items-center gap-3 no-underline hover:opacity-80">
      <span className="w-16 shrink-0 text-center rounded-full bg-sky-900/60 text-sky-300 text-xs font-mono py-1">GET</span>
      <span className="text-slate-200 font-mono text-sm">/v1/apps/{'{app_name}'}/volumes</span>
    </a>

    <a href="#create-a-volume" className="flex items-center gap-3 no-underline hover:opacity-80">
      <span className="w-16 shrink-0 text-center rounded-full bg-emerald-800/60 text-emerald-300 text-xs font-mono py-1">POST</span>
      <span className="text-slate-200 font-mono text-sm">/v1/apps/{'{app_name}'}/volumes</span>
    </a>

    <a href="#get-a-specific-volume" className="flex items-center gap-3 no-underline hover:opacity-80">
      <span className="w-16 shrink-0 text-center rounded-full bg-sky-900/60 text-sky-300 text-xs font-mono py-1">GET</span>
      <span className="text-slate-200 font-mono text-sm">/v1/apps/{'{app_name}'}/volumes/{'{volume_id}'}</span>
    </a>

    <a href="#update-a-volume" className="flex items-center gap-3 no-underline hover:opacity-80">
      <span className="w-16 shrink-0 text-center rounded-full bg-amber-900/60 text-amber-300 text-xs font-mono py-1">PUT</span>
      <span className="text-slate-200 font-mono text-sm">/v1/apps/{'{app_name}'}/volumes/{'{volume_id}'}</span>
    </a>

    <a href="#delete-a-volume-permanently" className="flex items-center gap-3 no-underline hover:opacity-80">
      <span className="w-16 shrink-0 text-center rounded-full bg-rose-950/60 text-rose-300 text-xs font-mono py-1">DELETE</span>
      <span className="text-slate-200 font-mono text-sm">/v1/apps/{'{app_name}'}/volumes/{'{volume_id}'}</span>
    </a>

    <a href="#extend-a-volume" className="flex items-center gap-3 no-underline hover:opacity-80">
      <span className="w-16 shrink-0 text-center rounded-full bg-amber-900/60 text-amber-300 text-xs font-mono py-1">PUT</span>
      <span className="text-slate-200 font-mono text-sm">/v1/apps/{'{app_name}'}/volumes/{'{volume_id}'}/extend</span>
    </a>

    <a href="#get-a-list-of-snapshots-for-a-volume" className="flex items-center gap-3 no-underline hover:opacity-80">
      <span className="w-16 shrink-0 text-center rounded-full bg-sky-900/60 text-sky-300 text-xs font-mono py-1">GET</span>
      <span className="text-slate-200 font-mono text-sm">/v1/apps/{'{app_name}'}/volumes/{'{volume_id}'}/snapshots</span>
    </a>

    <a href="#create-an-on-demand-volume-snapshot-beta" className="flex items-center gap-3 no-underline hover:opacity-80">
      <span className="w-16 shrink-0 text-center rounded-full bg-emerald-800/60 text-emerald-300 text-xs font-mono py-1">POST</span>
      <span className="text-slate-200 font-mono text-sm">/v1/apps/{'{app_name}'}/volumes/{'{volume_id}'}/snapshots</span>
    </a>
  </div>
</div>

## Volume properties

| Property              | Type    | Description                                                                        |
| --------------------- | ------- | ---------------------------------------------------------------------------------- |
| `auto_backup_enabled` | bool    | Enable automatic daily snapshots. Default true.                                    |
| `attached_alloc_id`   | string  | n/a                                                                                |
| `attached_machine_id` | string  | The ID of the Machine that’s attached to the volume.                               |
| `block_size`          | int     | The size of each memory block in bytes.                                            |
| `blocks`              | int     | The total number of blocks in the volume.                                          |
| `blocks _avail`       | int     | The number of blocks available for data in the volume.                             |
| `blocks_free`         | int     | The total number of blocks free for data and root user ops.                        |
| `created_at`          | string  | The date and time the volume was created.                                          |
| `encrypted`           | boolean | Whether the volume is encrypted. Default true.                                     |
| `fstype`              | string  | The file system type.                                                              |
| `id`                  | string  | The volume ID.                                                                     |
| `name`                | string  | The volume name.                                                                   |
| `region`              | string  | The region where the volume resides, or the target region for volume create.       |
| `size_gb`             | int     | The size of the volume in GB.                                                      |
| `snapshot_retention`  | int     | The number of days to retain snapshots. Defaults to 5 when not set. Min 1, max 60. |
| `state`               | string  | The state of the volume.                                                           |
| `zone`                | string  | The hardware zone on which the volume resides.                                     |

## List all the volumes in an app

`GET /apps/{app_name}/volumes`

Given the name of a Fly App, get a list of all the volumes that belong to it.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App to list volumes for.
</ParamField>

```sh title="GET/v1/apps/{app_name}/volumes" theme={null}
curl -i -X GET \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes" 
```

```json title="Status: 200 OK - Example response" theme={null}
[
    {
        "id": "vol_9vw681egy1jj5xm4",
        "name": "disk",
        "state": "created",
        "size_gb": 3,
        "region": "yul",
        "zone": "09cd",
        "encrypted": true,
        "attached_machine_id": "908057ef21e487",
        "attached_alloc_id": null,
        "created_at": "2023-09-01T19:47:14.774Z",
        "blocks": 768250,
        "block_size": 4096,
        "blocks_free": 768244,
        "blocks_avail": 730163,
        "fstype": "ext4",
        "snapshot_retention": 5,
        "auto_backup_enabled": true,
        "host_dedication_key": ""
    },
    {
        "id": "vol_q4qeekqzxze29dw4",
        "name": "disk",
        "state": "created",
        "size_gb": 3,
        "region": "iad",
        "zone": "a4df",
        "encrypted": true,
        "attached_machine_id": null,
        "attached_alloc_id": null,
        "created_at": "2024-01-02T21:16:38.996Z",
        "blocks": 751366,
        "block_size": 4096,
        "blocks_free": 751360,
        "blocks_avail": 708148,
        "fstype": "ext4",
        "snapshot_retention": 5,
        "auto_backup_enabled": true,
        "host_dedication_key": ""
    }
]
```

## Create a volume

`POST /apps/{app_name}/volumes`

Create a volume for a specific app according to the configuration provided in the request body.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App to create a volume for.
</ParamField>

```sh title="POST/v1/apps/{app_name}/volumes" theme={null}
curl -i -X POST \\
      -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
      "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes" \\
      -d '{
      "name": "my_app_vol",
      "region": "ord",
      "size_gb": 10
    }'
```

```json title="Request body schema" theme={null}
{
  "auto_backup_enabled": true,
  "compute": {
    "cpu_kind": "string",
    "cpus": 0,
    "gpu_kind": "string",
    "gpus": 0,
    "host_dedication_id": "string",
    "kernel_args": ["string"],
    "memory_mb": 0
  },
  "encrypted": true,
  "fstype": "string",
  "machines_only": true,
  "name": "string",
  "region": "string",
  "require_unique_zone": true,
  "size_gb": 0,
  "snapshot_id": "string",
  "snapshot_retention": 0,
  "source_volume_id": "string"
}
```

#### Body parameters

<ParamField body="auto_backup_enabled" type="bool">
  Enable automatic daily snapshots. Default true.
</ParamField>

<ParamField body="compute" type="object">
  An optional object defining the compute specifications for the expected Machine size and type that the volume will attach to. Used to place the volume on hardware that can host that Machine.

  <Expandable title="compute properties">
    <ParamField body="compute.cpu_kind" type="string">
      The CPU kind, `shared` or `performance`.
    </ParamField>

    <ParamField body="compute.cpus" type="int">
      The number of CPUs.
    </ParamField>

    <ParamField body="compute.gpu_kind" type="string">
      The GPU kind, for example `a100-pcie-40gb`.
    </ParamField>

    <ParamField body="compute.gpus" type="int">
      The number of GPUs.
    </ParamField>

    <ParamField body="compute.host_dedication_id" type="string">
      The ID of a dedicated host to place the volume on.
    </ParamField>

    <ParamField body="compute.kernel_args" type="string[]">
      Kernel arguments for the Machine.
    </ParamField>

    <ParamField body="compute.memory_mb" type="int">
      Memory in MB.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fstype" type="string">
  The file system type. Default `ext4`.
</ParamField>

<ParamField body="machines_only" type="boolean">
  If true, the volume can only be attached to Machines (not Nomad allocations).
</ParamField>

<ParamField body="encrypted" type="boolean">
  Whether to encrypt the volume. Default true.
</ParamField>

<ParamField body="name" type="string" required>
  The name for the new volume.
</ParamField>

<ParamField body="region" type="string">
  The region where the volume will be created. Defaults to the Machine’s region if attached. If not attached, defaults to the app’s primary region.
</ParamField>

<ParamField body="size_gb" type="int">
  The size of the volume in GB. Default 3.
</ParamField>

<ParamField body="snapshot_id" type="string">
  The ID of the volume snapshot to use to create the new volume.
</ParamField>

<ParamField body="source_volume_id" type="string">
  The ID of the source volume for the volume fork.
</ParamField>

<ParamField body="require_unique_zone" type="boolean">
  If true, we will provision this volume on hardware that doesn’t have another volume with the same name on it. The typical pattern is to create as many volumes as you need, all with the same name and `require_unique_zone: true`. This will keep your app available in case a host goes down. This flag can also cause volume creation to fail, in case we have used up all unique zones, in which case you probably want to set it to false. Default true.
</ParamField>

<ParamField body="snapshot_retention" type="int">
  The number of days to retain snapshots. Defaults to 5 when not set. Min 1, max 60.
</ParamField>

```json title="Status: 200 OK - Example response" theme={null}
{
    "id": "vol_340088w293z35lp4",
    "name": "new_1028_vol",
    "state": "created",
    "size_gb": 10,
    "region": "ord",
    "zone": "84d3",
    "encrypted": true,
    "attached_machine_id": null,
    "attached_alloc_id": null,
    "created_at": "2023-11-27T21:47:06.837Z",
    "blocks": 0,
    "block_size": 0,
    "blocks_free": 0,
    "blocks_avail": 0,
    "fstype": "",
    "snapshot_retention": 5,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}
```

## Get a specific volume

`GET /apps/{app_name}/volumes/{volume_id}`

Retrieve details about a specific volume by its ID within an app.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App the volume belongs to.
</ParamField>

<ParamField path="volume_id" type="string" required>
  The ID of the volume to get.
</ParamField>

```sh title="GET/v1/apps/{app_name}/volumes/{volume_id}" theme={null}
curl -i -X GET \\
         -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
         "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r" 
```

```json title="Status: 200 OK - Example response" theme={null}
{
    "id": "vvol_6r7ye90k98ynwk1r",
    "name": "disk",
    "state": "created",
    "size_gb": 3,
    "region": "yul",
    "zone": "09cd",
    "encrypted": true,
    "attached_machine_id": "6e8297dc244287",
    "attached_alloc_id": null,
    "created_at": "2023-09-01T19:47:14.774Z",
    "blocks": 768250,
    "block_size": 4096,
    "blocks_free": 768244,
    "blocks_avail": 730163,
    "fstype": "ext4",
    "snapshot_retention": 5,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}
```

## Update a volume

`PUT /apps/{app_name}/volumes/{volume_id}`

Update parameters on the volume.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App to create a volume for.
</ParamField>

<ParamField path="volume_id" type="string" required>
  The ID of the volume to get.
</ParamField>

#### Body parameters

<ParamField body="auto_backup_enabled" type="bool">
  Enable automatic daily snapshots. Default true.
</ParamField>

<ParamField body="snapshot_retention" type="int">
  The number of days to retain snapshots. Defaults to 5 when not set. Min 1, max 60.
</ParamField>

```sh title="PUT/v1/apps/{app_name}/volumes/{volume_id}" theme={null}
curl -i -X PUT \\
      -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
      "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r" \\
      -d '{
      "snapshot_retention": 10
    }'
```

```json title="Status: 200 OK - Example response" theme={null}
{
    "id": "vol_340088w293z35lp4",
    "name": "new_1028_vol",
    "state": "created",
    "size_gb": 10,
    "region": "ord",
    "zone": "84d3",
    "encrypted": true,
    "attached_machine_id": null,
    "attached_alloc_id": null,
    "created_at": "2023-11-27T21:47:06.837Z",
    "blocks": 0,
    "block_size": 0,
    "blocks_free": 0,
    "blocks_avail": 0,
    "fstype": "",
    "snapshot_retention": 10,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}
```

## Delete a volume permanently

`DELETE /apps/{app_name}/volumes/{volume_id}`

Delete a volume. This action cannot be undone.

Given the name of a Fly App and the volume ID of a Fly volume, delete the volume.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App the volume belongs to.
</ParamField>

<ParamField path="volume_id" type="string" required>
  The ID of the volume to permanently delete.
</ParamField>

```sh title="DELETE/v1/apps/{app_name}/volumes/{volume_id}" theme={null}
curl -i -X DELETE \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r" 
```

```json title="Status: 200 OK - Example response" theme={null}
{
    "id": "vol_grnejj355dqdj9kr",
    "name": "new_1028_vol",
    "state": "destroyed",
    "size_gb": 3,
    "region": "yyz",
    "zone": "aeee",
    "encrypted": true,
    "attached_machine_id": null,
    "attached_alloc_id": null,
    "created_at": "2023-12-07T21:35:57.42Z",
    "blocks": 0,
    "block_size": 0,
    "blocks_free": 0,
    "blocks_avail": 0,
    "fstype": "",
    "snapshot_retention": 0,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}
```

## Extend a volume

`PUT /apps/{app_name}/volumes/{volume_id}/extend`

Given the name of a Fly App and a volume ID, you can make a volume bigger by extending it. You can extend (increase) a volume’s size, but you can’t make a volume smaller.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App the volume belongs to.
</ParamField>

<ParamField path="volume_id" type="string" required>
  The ID of the volume to extend.
</ParamField>

#### Body parameters

<ParamField body="size_gb" type="integer" required>
  The size in GB to make the volume.
</ParamField>

```sh title="PUT/v1/apps/{app_name}/volumes/{volume_id}/extend" theme={null}
curl -i -X PUT \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r/extend" \\
    -d '{
    "size_gb": 10,
}'
```

```json title="Status: 200 OK - Example response" theme={null}
{
    "volume": {
        "id": "vol_9vw681egy1jj5xm4",
        "name": "disk",
        "state": "created",
        "size_gb": 10,
        "region": "yul",
        "zone": "09cd",
        "encrypted": true,
        "attached_machine_id": "6e8297dc244287",
        "attached_alloc_id": null,
        "created_at": "2023-09-01T19:47:14.774Z",
        "blocks": 0,
        "block_size": 0,
        "blocks_free": 0,
        "blocks_avail": 0,
        "fstype": "",
        "snapshot_retention": 5,
        "auto_backup_enabled": true,
        "host_dedication_key": ""
    },
    "needs_restart": false
}
```

If `needs_restart` is true, then your Machine needs to be restarted to make use of the added space.

## Get a list of snapshots for a volume

`GET /apps/{app_name}/volumes/{volume_id}/snapshots`

Given the name of a Fly app and a volume ID, list the available snapshots for that volume.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App to list snapshots for.
</ParamField>

<ParamField path="volume_id" type="string" required>
  The ID of the volume to list snapshots for.
</ParamField>

```sh title="GET/v1/apps/{app_name}/volumes/{volume_id}/snapshots" theme={null}
curl -i -X GET \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r/snapshots" \\
```

```json title="Status: 200 OK - Example response" theme={null}
[
    {
        "id": "vs_4LNvXLLK0P6tk6KgqoexaBw",
        "size": 36007729,
        "digest": "76d64a69199766d1600d46f0fd48ad9c-1",
        "created_at": "2023-12-02T20:59:35+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_3NlZ9NNmpvoSPqG6DO8BkDy",
        "size": 36007729,
        "digest": "e06b15e5467de62c5d505fa57923db93-1",
        "created_at": "2023-12-03T21:00:35+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_Ql8xbllZOYDSDgo2D7NYGj",
        "size": 36007729,
        "digest": "c37d2a590a351fa561fdb1ffd2f53d62-1",
        "created_at": "2023-12-04T21:01:35+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_x4AxX44lmpbcpap7vwX5x8e",
        "size": 36007729,
        "digest": "91fac554e5261d8f4eb6f7b69e88c8f9-1",
        "created_at": "2023-12-05T21:01:55+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_DkV2wkk7av1c9Kmlv79PL4o",
        "size": 36007729,
        "digest": "d78b5ff73a87b2bdfecb4a87c89c312b-1",
        "created_at": "2023-12-06T21:02:55+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_K8z1w88ZBOys22zqKGZ36R",
        "size": 36007729,
        "digest": "95dfe85046c67834566ccff2a29b18ec-1",
        "created_at": "2023-12-07T21:03:25+00:00",
        "retention_days": 10
    }
]
```

## Create a volume from a snapshot

`POST /apps/{app_name}/volumes`

Create a new volume from a snapshot backup.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App to create a volume for.
</ParamField>

#### Body parameters

<ParamField body="name" type="string" required>
  The name for the new volume.
</ParamField>

<ParamField body="region" type="string" required>
  The target region. Must be in the same region as the Machine you want to attach it to.
</ParamField>

<ParamField body="size_gb" type="int">
  The size of the volume in GB. Default 3.
</ParamField>

<ParamField body="snapshot_id" type="string">
  The ID of the volume snapshot to use to create the new volume.
</ParamField>

```sh title="POST/v1/apps/{app_name}/volumes" theme={null}
curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes" \\
  -d '{
  "name": "my-app-vol",
  "region": "yyz",
  "size_gb": 3,
  "snapshot_id": "vs_evl65mZQ937tQ16xGGDX8BN",
}'
```

```json title="Status: 200 OK - Example response" theme={null}
{
    "id": "vol_6vj0ggxl7zjkm2zr",
    "name": "new_1028_vol",
    "state": "restoring",
    "size_gb": 3,
    "region": "yyz",
    "zone": "75ec",
    "encrypted": true,
    "attached_machine_id": null,
    "attached_alloc_id": null,
    "created_at": "2024-02-23T00:41:02.411Z",
    "blocks": 0,
    "block_size": 0,
    "blocks_free": 0,
    "blocks_avail": 0,
    "fstype": "",
    "snapshot_retention": 5,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}
```

If you wait a moment and then get the new volume, the state should be `“created”`.

## Create an on-demand volume snapshot (beta)

`POST /apps/{app_name}/volumes/{volume_id}/snapshots`

Create an on-demand volume snapshot.

#### Path parameters

<ParamField path="app_name" type="string" required>
  The name of the Fly App to create a snapshot for.
</ParamField>

<ParamField path="volume_id" type="string" required>
  The ID of the volume to create a snapshot of.
</ParamField>

```sh title="POST/v1/apps/{app_name}/volumes/{volume_id}/snapshots" theme={null}
curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r/snapshots"
```

```json title="Status: 200 OK - Example response" theme={null}
{
    "Msg": {
        "backup": {
            "id": "85999",
            "app_id": "1700318",
            "volume_id": "9151365284627104",
            "state": "prepare",
            "type": "BACKUP_TYPE_ON_DEMAND",
            "message": "",
            "created_at": "2024-02-16T19:30:43.914350121Z",
            "updated_at": "2024-02-16T19:30:43.914350121Z",
            "finished_at": null,
            "graph_id": "vs_gwMAXwwLjOVuo7jL96v2kGXU2"
        }
    }
}
```

Wait a few moments for the snapshot to get created and then [get the list of snapshots](#get-a-list-of-snapshots-for-a-volume) to confirm.

## Related topics

* [Working with the Machines API](/machines/api/working-with-machines-api/)
* [Apps resource](/machines/api/apps-resource/) reference
* [Machines resource](/machines/api/machines-resource/) reference
* [Tokens resource](/machines/api/tokens-resource) reference