Skip to main content
Before you start, ensure that you have API Key with Disks -> Read and write permission

​
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

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: 
[
    {
        "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
Filter by regions or data_center_id to find disks in specific locations where you plan to run your GPU instances.

​
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

{
  "disk": {
    "size": 500,
    "name": "training-dataset",
    "dataCenterId": "US-1"
  },
  "provider": {
    "type": "hyperstack"
  }
}

​
Parameters

ParameterRequiredDescription
disk.sizeYesDisk size in GB (must be between minCount and maxCount from availability)
disk.nameNoHuman-friendly name for the disk (auto-generated if not provided)
disk.cloudIdYes*Cloud ID from the availability response (*if provided in availability response)
disk.dataCenterIdYes*Data center ID from availability (*if provided in availability response)
provider.typeYesProvider type from availability response (e.g., hyperstack, runpod)

​
Example: Creating a 500GB Disk

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: 
{
  "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
Disks are billed continuously from creation until termination, regardless of whether they’re attached to an instance.

​
Listing Your Disks

Retrieve all disks associated with your account: 
curl --request GET \
  --url 'https://api.primeintellect.ai/api/v1/disks/?limit=50&offset=0' \
  --header 'Authorization: Bearer your_api_key'

​
Query Parameters

ParameterDefaultDescription
limit50Number of results per page (max 200)
offset0Number of results to skip for pagination

​
Response

{
  "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: 
curl --request GET \
  --url https://api.primeintellect.ai/api/v1/disks/fdb5205fd9b14c9d804d3f70b4c96da0 \
  --header 'Authorization: Bearer your_api_key'

​
Response

{
  "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: 
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

{
  "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. 
curl --request DELETE \
  --url https://api.primeintellect.ai/api/v1/disks/fdb5205fd9b14c9d804d3f70b4c96da0 \
  --header 'Authorization: Bearer your_api_key'

​
Response

{
  "status": "TERMINATED"
}
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.
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.

​
Disk Status Values

Disks go through different statuses during their lifecycle:
StatusDescription
PROVISIONINGDisk is being created
PENDINGDisk status is changing
ACTIVEDisk is ready and can be attached to instances or deleted
STOPPEDDisk is stopped
ERRORAn error occurred during disk operations
DELETINGDisk is being deleted
TERMINATEDDisk has been deleted
UNKNOWNDisk status is unknown (cannot access the current status)
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.

​
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 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