Runpod

CAUTION: api.runpod.io is GraphQL only. REST calls to api.runpod.io will fail silently. Always use rest.runpod.io for REST.

1. Check GPU Availability

Use GraphQL — REST has no availability filter.

POST https://api.runpod.io/graphql

query {
  gpuTypes {
    id
    displayName
    memoryInGb
    communityPrice
    securePrice
    stockStatus        # LOW, MEDIUM, HIGH, or null (unavailable)
    communityCloud
    secureCloud
  }
}

Common GPU IDs

GPU availability is seconds-level volatile for premium cards (H100, A100, L40S). Always wrap deploys in retry logic with a fallback GPU list.

Suggested Fallback Chains

2. Create a Pod

REST (preferred)

POST https://rest.runpod.io/v1/pods
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "name": "my-pod",
  "imageName": "runpod/pytorch:2.4.0-py3.11-cuda12.4.1-devel-ubuntu22.04",
  "gpuTypeIds": ["NVIDIA L40S"],
  "gpuCount": 1,
  "cloudType": "ALL",
  "containerDiskInGb": 50,
  "volumeInGb": 100,
  "volumeMountPath": "/workspace",
  "ports": ["8888/http", "22/tcp"],
  "env": {
    "JUPYTER_PASSWORD": "mypassword",
    "HF_TOKEN": "hf_..."
  }
}

Returns 201 with full pod object including id.

Full Field Reference (REST POST /pods)

GraphQL (use for spot instances)

Spot instances (podRentInterruptable) are only available via GraphQL.

POST https://api.runpod.io/graphql

mutation {
  podRentInterruptable(input: {
    name: "spot-training"
    imageName: "runpod/pytorch:2.4.0-py3.11-cuda12.4.1-devel-ubuntu22.04"
    gpuTypeId: "NVIDIA L40S"
    gpuCount: 1
    cloudType: SECURE
    bidPerGpu: 0.40
    containerDiskInGb: 50
    volumeInGb: 100
    volumeMountPath: "/workspace"
    ports: "8888/http,22/tcp"
    env: [{ key: "HF_TOKEN", value: "hf_..." }]
  }) {
    id
    machineId
    machine { podHostId }
  }
}

CRITICAL DIFFERENCE: GraphQL env is [{key, value}] array. REST env is {"key": "value"} object. GraphQL gpuTypeId is singular string. REST gpuTypeIds is plural array. GraphQL ports is a single comma-separated string. REST ports is an array.

SPOT WARNING: Interruptible pods can be terminated at any time with zero notice. Always checkpoint work to network volumes or external storage.

3. List Pods

REST

GET https://rest.runpod.io/v1/pods

Returns array of pod objects with fields: id, name, desiredStatus (RUNNING/EXITED/TERMINATED), costPerHr, gpu, image, ports, publicIp, portMappings, env, volumeInGb, containerDiskInGb, machine, lastStatusChange, interruptible, locked.

Get single pod

GET https://rest.runpod.io/v1/pods/{podId}

Runtime metrics (GraphQL only)

REST doesn't return live GPU utilization or container metrics. Use GraphQL:

query {
  myself {
    pods {
      id
      name
      desiredStatus
      costPerHr
      runtime {
        uptimeInSeconds
        ports { ip isIpPublic privatePort publicPort type }
        gpus { id gpuUtilPercent memoryUtilPercent }
        container { cpuPercent memoryPercent }
      }
    }
  }
}

4. Pod Lifecycle

Stop (releases GPU, preserves volume)

POST https://rest.runpod.io/v1/pods/{podId}/stop

Start / Resume

POST https://rest.runpod.io/v1/pods/{podId}/start

Restart (soft restart, keeps GPU)

POST https://rest.runpod.io/v1/pods/{podId}/restart

Reset (wipes container disk, keeps volume)

POST https://rest.runpod.io/v1/pods/{podId}/reset

Terminate (permanent deletion)

DELETE https://rest.runpod.io/v1/pods/{podId}

TERMINATE IS IRREVERSIBLE. All data not on a network volume is permanently destroyed.

Resume spot instance (GraphQL only)

mutation {
  podBidResume(input: {
    podId: "abc123"
    bidPerGpu: 0.40
    gpuCount: 1
  }) {
    id
    desiredStatus
  }
}

5. Update a Pod

PATCH https://rest.runpod.io/v1/pods/{podId}
Content-Type: application/json

{
  "env": {"NEW_VAR": "value"},
  "ports": ["8888/http", "22/tcp", "5000/http"],
  "volumeInGb": 200,
  "imageName": "runpod/pytorch:2.8.0-py3.11-cuda12.6-devel-ubuntu22.04"
}

Updatable fields: containerDiskInGb, containerRegistryAuthId, dockerEntrypoint, dockerStartCmd, env, globalNetworking, imageName, locked, name, ports, volumeInGb, volumeMountPath.

Updates may trigger a pod reset. Warn user that running processes will be interrupted.

6. Network Volumes

Network volumes are persistent storage independent of any pod. They survive pod termination and can be attached to any pod in the same datacenter. Critical for ML workflows.

Create

POST https://rest.runpod.io/v1/networkvolumes

{
  "name": "training-data",
  "size": 100,
  "dataCenterId": "US-TX-3"
}

List

GET https://rest.runpod.io/v1/networkvolumes

Get

GET https://rest.runpod.io/v1/networkvolumes/{networkVolumeId}

Update

PATCH https://rest.runpod.io/v1/networkvolumes/{networkVolumeId}

Delete

DELETE https://rest.runpod.io/v1/networkvolumes/{networkVolumeId}

Attach to pod at creation

Set networkVolumeId in the pod create call. This replaces the local volume — the network volume mounts at volumeMountPath (default /workspace).

{
  "name": "my-pod",
  "imageName": "runpod/pytorch:2.4.0-py3.11-cuda12.4.1-devel-ubuntu22.04",
  "gpuTypeIds": ["NVIDIA L40S"],
  "networkVolumeId": "vol_abc123",
  "volumeMountPath": "/workspace"
}

Gotchas

• Cannot attach/detach after pod creation. Must terminate and recreate.
• Size cannot be decreased, only increased. Over 4 TB requires support contact.
• Concurrent writes from multiple pods corrupt data. One writer at a time.
• Pod and volume must be in the same datacenter. Specify dataCenterIds on pod create to match.
• $0.07/GB/month for first TB, $0.05/GB/month after. Volumes with no payment method risk deletion.

7. Templates

List

GET https://rest.runpod.io/v1/templates

Create

POST https://rest.runpod.io/v1/templates

{
  "name": "my-training-template",
  "imageName": "runpod/pytorch:2.4.0-py3.11-cuda12.4.1-devel-ubuntu22.04",
  "containerDiskInGb": 50,
  "volumeInGb": 100,
  "volumeMountPath": "/workspace",
  "ports": ["8888/http", "22/tcp"],
  "env": {"JUPYTER_PASSWORD": "default"},
  "dockerStartCmd": []
}

Update

PATCH https://rest.runpod.io/v1/templates/{templateId}

Delete

DELETE https://rest.runpod.io/v1/templates/{templateId}

Template must not be in use by any pod or serverless endpoint.

8. Connecting to a Pod

HTTP Proxy (easiest, has timeout)