Pods API

Pods are GPU compute instances provisioned on RunPod. They boot with your lab's environment, run experiments, and tear down when finished. The Pods API gives you full control over the lifecycle, SSH access, and cost monitoring.

Pod Status

Status	Description
creating	Pod is being provisioned on RunPod
running	Pod is online and executing or idle
stopped	Pod has been stopped (can be restarted)
terminated	Pod has been permanently terminated

Create a Pod

Provision a new GPU pod.

Lab this pod belongs to.

GPU type: H200, H100, A100.

Number of GPUs. Multi-GPU pods available for H100 and A100.

Maximum runtime in hours. Pod auto-terminates after this limit. Omit for no limit (controlled by budget).

Docker image for the pod environment.

Environment variables to set on the pod.

Persistent volume size in GB.

curl -X POST https://api.hubify.com/v1/pods \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "gpuType": "H200",
    "maxHours": 8,
    "env": {
      "COBAYA_PACKAGES": "/workspace/packages",
      "EXPERIMENT_ID": "EXP-054"
    },
    "volumeSize": 100
  }'

const pod = await hubify.pods.create({
  labId: "j57a8k9m2n3p4q5r",
  gpuType: "H200",
  maxHours: 8,
  env: {
    COBAYA_PACKAGES: "/workspace/packages",
    EXPERIMENT_ID: "EXP-054",
  },
  volumeSize: 100,
});

Convex document ID.
Parent lab ID.
Always `runpod`.
RunPod pod identifier.
GPU type.
Current status.
SSH hostname (available once running).
SSH port (available once running).
Hourly cost in USD.
Creation timestamp (ms).

List Pods

Lab ID.

Filter by status: creating, running, stopped, terminated.

curl "https://api.hubify.com/v1/pods?labId=j57a8k9m2n3p4q5r&status=running" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const pods = await hubify.pods.list({
  labId: "j57a8k9m2n3p4q5r",
  status: "running",
});

Get Pod Status

Detailed status including GPU utilization, memory, and idle time.

curl https://api.hubify.com/v1/pods/pod_abc123 \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const pod = await hubify.pods.get({ podId: "pod_abc123" });

RunPod pod ID.
Current status.
GPU type.
Current GPU utilization (0-1).
Current VRAM usage in GB.
Total VRAM in GB.
Minutes since last GPU activity.
Whether the pod is frozen (budget limit reached).
Reason for freeze, if applicable.
Total uptime in seconds.
Cost accumulated so far in USD.
SSH hostname.
SSH port.

SSH Configuration

Once a pod is running, SSH credentials are available in the pod details.

curl https://api.hubify.com/v1/pods/pod_abc123/ssh \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const ssh = await hubify.pods.getSSH({ podId: "pod_abc123" });
// { host: "205.196.19.52", port: 11452, user: "root" }

# Connect via SSH
ssh root@205.196.19.52 -p 11452

Stop a Pod

Stop a running pod. The persistent volume is preserved. The pod can be restarted later.

curl -X POST https://api.hubify.com/v1/pods/pod_abc123/stop \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.pods.stop({ podId: "pod_abc123" });

Restart a Pod

Restart a stopped pod with the same configuration.

curl -X POST https://api.hubify.com/v1/pods/pod_abc123/restart \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.pods.restart({ podId: "pod_abc123" });

Terminate a Pod

Permanently terminate a pod. The persistent volume is retained for 7 days, then deleted.

Warning: Termination is irreversible. Make sure experiment results have been synced back to the lab before terminating.

curl -X POST https://api.hubify.com/v1/pods/pod_abc123/terminate \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.pods.terminate({ podId: "pod_abc123" });

GPU Types and Pricing

GPU	VRAM	Cost/hr (approx.)	Best For
H200	141 GB	$4.00	Large MCMC, foundation models, multi-survey sweeps
H100	80 GB	$2.50	Training runs, medium MCMC, anomaly detection
A100	80 GB	$1.50	General GPU compute, smaller models

Note: Prices are approximate and depend on RunPod availability. Actual costs are tracked in the cost_tracking table and visible via the cost endpoints.

Cost Tracking

Get Current Month Costs

curl "https://api.hubify.com/v1/pods/costs?labId=j57a8k9m2n3p4q5r&month=current" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const costs = await hubify.pods.getCosts({
  labId: "j57a8k9m2n3p4q5r",
  month: "current",
});

Total GPU compute cost in USD.
Total LLM API cost in USD.
Storage cost in USD.
Combined total cost.
Total GPU hours consumed.
Experiments run this month.
Remaining budget in USD.
Percentage of budget used (0-1).

Idle Detection

Hubify monitors GPU utilization and alerts you when pods are sitting idle. This is accessible through the pod status endpoint (the idleMinutes field) and triggers notifications when a configurable threshold is exceeded.

Note: An idle GPU is a violation of the Hubify Labs philosophy. The system will suggest queued experiments to deploy on idle pods, and auto-deploy if you have auto-schedule enabled.

Configure Idle Threshold

curl -X PATCH https://api.hubify.com/v1/labs/dark-energy/settings \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idleAlertMinutes": 15, "autoScheduleEnabled": true}'

await hubify.labs.updateSettings({
  slug: "dark-energy",
  idleAlertMinutes: 15,
  autoScheduleEnabled: true,
});