Managing Disks - Prime Intellect Docs

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

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

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

Parameter	Default	Description
`limit`	50	Number of results per page (max 200)
`offset`	0	Number 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:

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)

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

Check GPU Availability - Filter GPUs by disk location
Provision GPU - Attach disks when creating instances
Managing Instances - Manage instances with attached disks

​Overview

​Finding Available Disk Options

​Query Disk Availability

​Understanding the Response

​Key Fields

​Creating a Disk

​Request Body Structure

​Parameters

​Example: Creating a 500GB Disk

​Response

​Cost Calculation

​Listing Your Disks

​Query Parameters

​Response

​Getting a Single Disk

​Response

​Updating a Disk

​Response

​Deleting a Disk

​Response

​Disk Status Values

​Common Use Cases

​Shared Training Data

​Model Checkpoints and Artifacts

​Multi-Node Distributed Training

​Best Practices

​Location Planning

​Size Planning

​Data Management

​Related Documentation

Overview

Finding Available Disk Options

Query Disk Availability

Understanding the Response

Key Fields

Creating a Disk

Request Body Structure

Parameters

Example: Creating a 500GB Disk

Response

Cost Calculation

Listing Your Disks

Query Parameters

Response

Getting a Single Disk

Response

Updating a Disk

Response

Deleting a Disk

Response

Disk Status Values

Common Use Cases

Shared Training Data

Model Checkpoints and Artifacts

Multi-Node Distributed Training

Best Practices

Location Planning

Size Planning

Data Management

Related Documentation