Instances API

Launch Instance

curl -X POST https://api.pulserun.dev/v1/instances \
  -H "Authorization: Bearer pr_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "gpu": "a100_80gb",
    "template": "pytorch",
    "docker_image": null,
    "disk_size_gb": 50,
    "region": "us",
    "spot": false,
    "ssh_key_id": "key_abc123",
    "provider": "auto",
    "auto_migrate": false,
    "auto_spot_recovery": false,
    "budget_limit": null
  }'

Request Body

Field	Type	Required	Description
`gpu`	string	✅	GPU type slug (e.g., `a100_80gb`, `h100_80gb`, `rtx_4090`)
`template`	string	✅	Template slug or `"custom"`
`docker_image`	string	No	Docker image (only for `"custom"` template)
`disk_size_gb`	integer	No	Disk size, default 50
`region`	string	No	`"us"`, `"eu"`, `"asia"`, `"any"` (default: `"any"`)
`spot`	boolean	No	Use spot instances (default: false)
`ssh_key_id`	string	No	SSH key to attach
`provider`	string	No	`"auto"` (cheapest) or force a specific provider
`auto_migrate`	boolean	No	Phase 3: auto-migrate on price drops
`auto_spot_recovery`	boolean	No	Phase 3: auto-restart on spot interruption
`budget_limit`	number	No	Phase 3: max spend in dollars

Response

{
  "id": "inst_abc123",
  "status": "provisioning",
  "gpu": "a100_80gb",
  "gpu_name": "NVIDIA A100 80GB",
  "provider": "vast_ai",
  "region": "us-east",
  "ip": null,
  "ssh_command": null,
  "jupyter_url": null,
  "cost_per_hour": 0.95,
  "template": "pytorch",
  "spot": false,
  "started_at": null,
  "created_at": "2026-03-01T12:00:00Z"
}

Once provisioned, ip, ssh_command, and jupyter_url will be populated.

List Instances

# All instances
curl https://api.pulserun.dev/v1/instances \
  -H "Authorization: Bearer pr_live_xxxxxxxxxxxxx"
 
# Filter by status
curl https://api.pulserun.dev/v1/instances?status=running \
  -H "Authorization: Bearer pr_live_xxxxxxxxxxxxx"

Get Instance

curl https://api.pulserun.dev/v1/instances/inst_abc123 \
  -H "Authorization: Bearer pr_live_xxxxxxxxxxxxx"

Stop Instance

Pause billing, keep disk state.

curl -X POST https://api.pulserun.dev/v1/instances/inst_abc123/stop \
  -H "Authorization: Bearer pr_live_xxxxxxxxxxxxx"

Start Instance

Resume a stopped instance.

curl -X POST https://api.pulserun.dev/v1/instances/inst_abc123/start \
  -H "Authorization: Bearer pr_live_xxxxxxxxxxxxx"

Terminate Instance

Permanently delete.

curl -X DELETE https://api.pulserun.dev/v1/instances/inst_abc123 \
  -H "Authorization: Bearer pr_live_xxxxxxxxxxxxx"

Get Instance Metrics (Phase 2)

curl https://api.pulserun.dev/v1/instances/inst_abc123/metrics \
  -H "Authorization: Bearer pr_live_xxxxxxxxxxxxx"

Returns GPU utilization, memory usage, disk usage, and uptime.

Authentication Pricing