HarvestGPU Documentation

Getting Started

HarvestGPU works with your existing GPU provider accounts. Here is how to get set up:

1. Create a HarvestGPU account

Sign up at /register or via the API. This gives you a HarvestGPU API key for authenticating requests.

2. Connect your GPU provider keys

Go to Dashboard Settings and add your API keys for one or more providers. You can also use the API:

curl -X POST http://localhost:5000/api/v1/providers/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "runpod", "api_key": "YOUR_RUNPOD_KEY", "label": "My RunPod"}'

3. Submit jobs

Jobs are routed across your connected providers to find the cheapest option. A built-in mock provider is always available for testing, even without any provider keys.

Supported providers and where to get API keys

Your keys are stored securely and only used to call provider APIs on your behalf. Billing for GPU usage goes directly through your provider accounts.

Quick Start

Get running in under a minute.

1. Get your API key

curl -X POST http://localhost:5000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Save the api_key from the response. It looks like hg_live_abc123...

2. Submit a GPU job

curl -X POST http://localhost:5000/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gpu": "H100",
    "image": "pytorch/pytorch:latest",
    "command": "python train.py",
    "priority": "cost"
  }'

3. Check job status

curl http://localhost:5000/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All authenticated endpoints accept two auth methods:

• API Key (recommended): Pass your API key as a Bearer token: Authorization: Bearer hg_live_...
• API Key Header: X-API-Key: hg_live_...
• JWT Token: Obtained from the login endpoint. Same Bearer header format.

Python SDK

Installation

pip install harvestgpu

Usage

from harvestgpu import HarvestGPU

gpu = HarvestGPU(api_key="hg_live_...")

# Submit a job - routes to cheapest provider
job = gpu.run(
    gpu="H100",
    image="pytorch/pytorch:latest",
    command="python train.py",
    budget_max=2.50,
)

print(job.status)        # "running"
print(job.provider)      # "mock" (or real provider)
print(job.cost_per_hour) # 2.86

# List your jobs
jobs = gpu.jobs()
for j in jobs:
    print(f"{j.id}: {j.gpu_type} on {j.provider} - {j.status}")

# Get current GPU pricing
pricing = gpu.pricing()
for p in pricing:
    print(f"{p.gpu_model}: ${p.price}/hr via {p.provider}")

# Stop a job
job.stop()

# Get logs
logs = job.logs()
print(logs)

CLI Tool

# Authenticate
harvestgpu auth login --key hg_live_...
harvestgpu auth whoami

# Run a GPU job
harvestgpu run --gpu H100 --image pytorch/pytorch:latest --command "python train.py"

# Manage jobs
harvestgpu jobs list
harvestgpu jobs status JOB_ID
harvestgpu jobs logs JOB_ID
harvestgpu jobs stop JOB_ID

# Check pricing
harvestgpu pricing
harvestgpu pricing --gpu H100

API Reference

Base URL: http://localhost:5000/api/v1

All responses follow this envelope:

{
  "status": "ok",      // or "error"
  "data": { ... },     // present on success
  "error": "message"   // present on error
}

Auth Endpoints

{
  "email": "you@example.com",
  "password": "min8chars",
  "company": "optional"
}

{
  "status": "ok",
  "data": {
    "user_id": "abc123",
    "email": "you@example.com",
    "api_key": "hg_live_xyz...",
    "token": "jwt.token.here"
  }
}

{"email": "you@example.com", "password": "your-password"}

Job Endpoints

{
  "gpu": "H100",                        // required
  "image": "pytorch/pytorch:latest",    // Docker image
  "command": "python train.py",         // Command to run
  "budget_max_per_hour": 2.50,          // optional price cap
  "max_duration_hours": 4,              // optional max runtime
  "priority": "cost"                    // "cost" | "speed" | "availability"
}

Provider Endpoints

Provider Key Endpoints

{
  "provider": "runpod",           // runpod | lambda | vastai | tensordock
  "api_key": "your-provider-key",
  "label": "My RunPod Account"    // optional
}

{
  "status": "ok",
  "data": {
    "provider": "runpod",
    "valid": true,
    "message": "Key is valid"
  }
}

Usage Endpoints

Webhook Endpoints

{"url": "https://your-app.com/webhook", "events": "job.completed,job.failed"}

Webhook Events

When configured, we send HTTP POST requests to your webhook URL with these events:

• job.completed - Job finished successfully
• job.failed - Job encountered an error
• job.stopped - Job was manually stopped

Payload Format

{
  "event": "job.completed",
  "job_id": "abc123",
  "gpu_type": "H100",
  "provider": "runpod",
  "total_cost": 3.45,
  "status": "completed",
  "timestamp": "2026-04-14T12:00:00Z"
}

Rate Limits

Error Handling

All errors return this format:

{
  "status": "error",
  "error": "Human-readable error message"
}