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

# Managing Disks

> How to create and manage network-attached storage disks

<Info>Before you start, ensure that you have [API Key](./api-keys) with `Disks -> Read and write` permission</Info>

## Overview

Network-attached disks provide persistent storage that can be shared across multiple GPU instances. Disks persist independently from instances, making them ideal for storing datasets, model checkpoints, and other data that needs to survive instance termination.

## Finding Available Disk Options

Before creating a disk, use the disk availability endpoint to find available storage options across different providers and datacenters.

### Query Disk Availability

```bash theme={null}
curl --request GET \
  --url 'https://api.primeintellect.ai/api/v1/availability/disks?regions=united_states&page=1&page_size=50' \
  --header 'Authorization: Bearer your_api_key'
```

### Understanding the Response

The response returns available disk configurations:

```json theme={null}
[
    {
        "cloudId": null,
        "provider": "hyperstack",
        "dataCenter": "US-1",
        "country": "US",
        "region": "united_states",
        "spec": {
            "minCount": 0,
            "defaultCount": 0,
            "maxCount": 100000,
            "pricePerUnit": 0.00015,
            "step": 1,
            "defaultIncludedInPrice": false,
            "additionalInfo": null
        },
        "stockStatus": "Available",
        "security": "secure_cloud",
        "isMultinode": false
    }
]
```

### Key Fields

* **`cloudId`**: Identifies the storage configuration (if applicable)
* **`provider`**: The provider offering the storage (e.g., `hyperstack`, `runpod`)
* **`dataCenter`**: Location where the disk will be created
* **`spec.minCount`**: Minimum disk size in GB
* **`spec.maxCount`**: Maximum disk size in GB
* **`spec.pricePerUnit`**: Cost per GB per hour
* **`isMultinode`**: Whether the disk can be attached to multiple instances

<Tip>
  Filter by `regions` or `data_center_id` to find disks in specific locations where you plan to run your GPU instances.
</Tip>

## Creating a Disk

Once you've identified a suitable disk configuration from the availability API, create a disk using the information from the availability response.

### Request Body Structure

```json theme={null}
{
  "disk": {
    "size": 500,
    "name": "training-dataset",
    "dataCenterId": "US-1"
  },
  "provider": {
    "type": "hyperstack"
  }
}
```

### Parameters

| Parameter           | Required | Description                                                                      |
| ------------------- | -------- | -------------------------------------------------------------------------------- |
| `disk.size`         | Yes      | Disk size in GB (must be between `minCount` and `maxCount` from availability)    |
| `disk.name`         | No       | Human-friendly name for the disk (auto-generated if not provided)                |
| `disk.cloudId`      | Yes\*    | Cloud ID from the availability response (\*if provided in availability response) |
| `disk.dataCenterId` | Yes\*    | Data center ID from availability (\*if provided in availability response)        |
| `provider.type`     | Yes      | Provider type from availability response (e.g., `hyperstack`, `runpod`)          |

### Example: Creating a 500GB Disk

```bash theme={null}
curl --request POST \
  --url https://api.primeintellect.ai/api/v1/disks/ \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "disk": {
    "size": 500,
    "name": "ml-training-data",
    "dataCenterId": "US-1"
  },
  "provider": {
    "type": "hyperstack"
  }
}'
```

### Response

On successful creation, you'll receive a `201 Created` response with the disk details:

```json theme={null}
{
  "id": "fdb5205fd9b14c9d804d3f70b4c96da0",
  "name": "ml-training-data",
  "createdAt": "2025-11-07T21:07:15.183000",
  "updatedAt": "2025-11-07T21:07:15.183000",
  "terminatedAt": null,
  "status": "PROVISIONING",
  "providerType": "hyperstack",
  "size": 500,
  "info": {
    "cloudId": null,
    "country": "US",
    "isMultinode": false,
    "dataCenterId": "US-1"
  },
  "priceHr": 0.075,
  "stoppedPriceHr": 0.075,
  "provisioningPriceHr": 0.0,
  "userId": "clvb0itli0000oxevorvgrpfn",
  "teamId": null,
  "walletId": "clvb0iv0c0004oxev5mnt1xiv",
  "pods": [],
  "clusters": []
}
```

### Cost Calculation

The hourly cost is calculated as:

```
Hourly Cost = size (GB) × pricePerUnit (from availability)
```

For a 500GB disk at \$0.00015/GB/hr:

```
500 GB × $0.00015/GB/hr = $0.075/hr
```

<Warning>
  Disks are billed continuously from creation until termination, regardless of whether they're attached to an instance.
</Warning>

## Listing Your Disks

Retrieve all disks associated with your account:

```bash theme={null}
curl --request GET \
  --url 'https://api.primeintellect.ai/api/v1/disks/?limit=50&offset=0' \
  --header 'Authorization: Bearer your_api_key'
```

### Query Parameters

| Parameter | Default | Description                              |
| --------- | ------- | ---------------------------------------- |
| `limit`   | 50      | Number of results per page (max 200)     |
| `offset`  | 0       | Number of results to skip for pagination |

### Response

```json theme={null}
{
  "totalCount": 1,
  "data": [
    {
      "id": "fdb5205fd9b14c9d804d3f70b4c96da0",
      "name": "ml-training-data",
      "createdAt": "2025-11-07T21:07:15.183000",
      "updatedAt": "2025-11-07T21:08:01.934000",
      "terminatedAt": null,
      "status": "ACTIVE",
      "providerType": "hyperstack",
      "size": 500,
      "info": {
        "cloudId": null,
        "country": "US",
        "isMultinode": false,
        "dataCenterId": "US-1"
      },
      "priceHr": 0.075,
      "stoppedPriceHr": 0.075,
      "provisioningPriceHr": 0.0,
      "userId": "clvb0itli0000oxevorvgrpfn",
      "teamId": null,
      "walletId": "clvb0iv0c0004oxev5mnt1xiv",
      "pods": [],
      "clusters": []
    }
  ],
  "limit": 50,
  "offset": 0
}
```

## Getting a Single Disk

Retrieve detailed information about a specific disk:

```bash theme={null}
curl --request GET \
  --url https://api.primeintellect.ai/api/v1/disks/fdb5205fd9b14c9d804d3f70b4c96da0 \
  --header 'Authorization: Bearer your_api_key'
```

### Response

```json theme={null}
{
  "id": "fdb5205fd9b14c9d804d3f70b4c96da0",
  "name": "ml-training-data",
  "createdAt": "2025-11-07T21:07:15.183000",
  "updatedAt": "2025-11-07T21:08:01.934000",
  "terminatedAt": null,
  "status": "ACTIVE",
  "providerType": "hyperstack",
  "size": 500,
  "info": {
    "cloudId": null,
    "country": "US",
    "isMultinode": false,
    "dataCenterId": "US-1"
  },
  "priceHr": 0.075,
  "stoppedPriceHr": 0.075,
  "provisioningPriceHr": 0.0,
  "userId": "clvb0itli0000oxevorvgrpfn",
  "teamId": null,
  "walletId": "clvb0iv0c0004oxev5mnt1xiv",
  "pods": [],
  "clusters": []
}
```

The response includes:

* **`pods`**: Array of pod IDs currently using this disk
* **`clusters`**: Array of cluster IDs currently using this disk
* **`info`**: Additional metadata about disk location and capabilities

## Updating a Disk

Currently, you can update the disk name:

```bash theme={null}
curl --request PATCH \
  --url https://api.primeintellect.ai/api/v1/disks/fdb5205fd9b14c9d804d3f70b4c96da0 \
  --header 'Authorization: Bearer your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "updated-training-dataset"
}'
```

### Response

```json theme={null}
{
  "id": "fdb5205fd9b14c9d804d3f70b4c96da0",
  "name": "updated-training-dataset"
}
```

## Deleting a Disk

Terminate a disk when you no longer need it. This will permanently delete the disk and all its data.

```bash theme={null}
curl --request DELETE \
  --url https://api.primeintellect.ai/api/v1/disks/fdb5205fd9b14c9d804d3f70b4c96da0 \
  --header 'Authorization: Bearer your_api_key'
```

### Response

```json theme={null}
{
  "status": "TERMINATED"
}
```

<Warning>
  **Disk deletion is permanent and irreversible**. All data stored on the disk will be lost. Make sure to backup any important data before deleting a disk.
</Warning>

<Info>
  **Detachment Timing**: The disk detachment process can take longer than instance termination. After terminating an instance, you may need to wait a few moments before the disk becomes available for deletion or reuse.
</Info>

## Disk Status Values

Disks go through different statuses during their lifecycle:

| Status         | Description                                               |
| -------------- | --------------------------------------------------------- |
| `PROVISIONING` | Disk is being created                                     |
| `PENDING`      | Disk status is changing                                   |
| `ACTIVE`       | Disk is ready and can be attached to instances or deleted |
| `STOPPED`      | Disk is stopped                                           |
| `ERROR`        | An error occurred during disk operations                  |
| `DELETING`     | Disk is being deleted                                     |
| `TERMINATED`   | Disk has been deleted                                     |
| `UNKNOWN`      | Disk status is unknown (cannot access the current status) |

<Note>
  After terminating an instance, the disk detachment process may take a few moments to complete. You may need to wait briefly before the disk becomes available for deletion or reattachment.
</Note>

## Common Use Cases

### Shared Training Data

Create large disks with your training datasets that can be reused across multiple training runs. This is ideal for storing preprocessed data, large image datasets, or any training data that needs to be accessed by multiple GPU instances. By keeping your data on a persistent disk, you avoid having to re-upload or regenerate datasets for each new training session.

### Model Checkpoints and Artifacts

Use disks to persist model checkpoints, trained weights, and training artifacts. This is especially valuable when running spot instances or interruptible workloads, as your progress remains safe even if the instance is terminated. You can resume training from the last checkpoint by simply attaching the disk to a new instance.

### Multi-Node Distributed Training

For distributed training across multiple GPUs or nodes, use multinode-compatible disks that can be accessed simultaneously by multiple instances. This enables shared access to training data and synchronized checkpointing across your distributed training cluster. Check the `isMultinode` field in the disk availability response to verify support.

## Best Practices

### Location Planning

* Create disks in the same datacenter where you plan to run GPU instances
* Use the [availability endpoint](./check-gpu-availability) with `disks` filter to find compatible GPUs

### Size Planning

* Start with the size needed - you cannot resize disks after creation
* Consider future growth when selecting disk size
* Remember that larger disks cost more per hour

### Data Management

* Regularly backup important data from disks
* Use descriptive names to identify disk contents

## Related Documentation

* [Check GPU Availability](./check-gpu-availability) - Filter GPUs by disk location
* [Provision GPU](./provision-gpu) - Attach disks when creating instances
* [Managing Instances](./managing-pods) - Manage instances with attached disks