API Hello World

The raw REST API is intended for advanced users only. These endpoints offer maximum flexibility but require you to manage all aspects of integration yourself. Most users will have a significantly better experience using the CLI or the Python SDK, which handle these details for you. If you are not sure whether you need direct API access, you almost certainly don’t — start with the CLI or SDK instead.

The Vast.ai REST API gives you programmatic access to the entire platform — authentication, account management, billing, GPU search, instance lifecycle, templates, volumes, serverless endpoints, and team administration. Anything you can do in the web console, you can automate through the API.

This guide walks through the core workflow: authenticate, search for a GPU, rent it, wait for it to boot, connect to it, and clean up. By the end you’ll understand the API calls needed to manage instances without touching the web console.

Prerequisites

• A Vast.ai account with credit (~$0.01–0.05, depending on test instance run time)
• curl installed
• python3 with the requests library (for the Python examples)

1. Get Your API Key

Generate an API key from the Keys page by clicking +New. Copy the key — you’ll need it for your API calls, and you’ll only see it once.

Export it as an environment variable:

export VAST_API_KEY="your-api-key-here"

The console creates a full-access key by default. You can also create scoped API keys with limited permissions via POST /api/v0/auth/apikeys/ — useful for CI/CD or shared tooling where you want to restrict access to read-only or instance-only operations. See the Create API Key endpoint for details.

2. Verify Authentication

Confirm your key works by fetching your account info. This returns your user ID, email, balance, and SSH key — a quick way to verify what your key grants access to.

cURL

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  "https://console.vast.ai/api/v0/users/current/"

{
  "id": 123456,
  "email": "[e-mail]",
  "credit": 25.00,
  "ssh_key": "ssh-rsa AAAAB3..."
}

The credit field shows your available credit, and ssh_key is the public key that will be injected into new instances.

If you get a 401 or 403, double-check your API key.

3. Search for GPUs

Find available machines using the bundles endpoint. This query returns the top 5 on-demand RTX 4090s sorted by deep learning performance benchmarked per dollar:

cURL

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verified": {"eq": true},
    "rentable": {"eq": true},
    "gpu_name": {"eq": "RTX 4090"},
    "num_gpus": {"eq": 1},
    "direct_port_count": {"gte": 1},
    "order": [["dlperf_per_dphtotal", "desc"]],
    "type": "on-demand",
    "limit": 5
  }' \
  "https://console.vast.ai/api/v0/bundles/"

Each parameter in the query above controls a different filter:

Parameter	Value	Meaning
verified	{"eq": true}	Only machines verified by Vast.ai (identity-checked hosts)
rentable	{"eq": true}	Only machines currently available to rent
gpu_name	{"eq": "RTX 4090"}	Filter to a specific GPU model
num_gpus	{"eq": 1}	Exactly 1 GPU per instance
direct_port_count	{"gte": 1}	At least 1 directly accessible port (needed for SSH)
order	[["dlperf_per_dphtotal", "desc"]]	Sort by deep learning performance per dollar, best value first
type	"on-demand"	On-demand pricing (vs. interruptible spot/bid)
limit	5	Return at most 5 results

The response contains an offers array. Note the id of the offer you want — you’ll use it in the next step. If no offers are returned, try relaxing your filters (e.g. a different GPU model or removing direct_port_count).

See the Search Offers reference for the full list of filter parameters and operators.

4. Create an Instance

Rent the machine by sending a PUT request to the asks endpoint. Replace OFFER_ID with the id from step 3.

The simplest approach is to create from a template, which bundles your image, startup commands, and launch settings into a reusable configuration:

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "template_hash_id": "YOUR_TEMPLATE_HASH",
    "disk": 20,
    "runtype": "ssh_direct"
  }' \
  "https://console.vast.ai/api/v0/asks/OFFER_ID/"

A template packages your Docker image, environment variables, and startup script so you don’t repeat them on every create call. See the Templates API guide for creating and managing templates.

If you don’t have a template yet, you can specify the image and startup commands directly:

cURL

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "image": "pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime",
    "disk": 20,
    "onstart": "echo hello && nvidia-smi",
    "runtype": "ssh_direct"
  }' \
  "https://console.vast.ai/api/v0/asks/OFFER_ID/"

{
  "success": true,
  "new_contract": 12345678,
  "instance_api_key": "d15a..."
}

Save the new_contract value — this is your instance ID. The instance_api_key provides scoped access for that specific instance (e.g., querying GET /api/v0/instances/{id}/ without your main API key).

Setting "runtype": "ssh_direct" gives you a direct SSH connection to the machine, which has lower latency than the default proxy SSH. Recommended for interactive work.

5. Wait Until Ready

The instance needs time to pull the Docker image and boot. Poll the status endpoint until actual_status is "running". Replace INSTANCE_ID with the new_contract value from step 4.

cURL

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  "https://console.vast.ai/api/v0/instances/INSTANCE_ID/"

Example response:

{
  "instances": {
    "actual_status": "loading",
    "ssh_host": "...",
    "ssh_port": 12345
  }
}

The actual_status field progresses through these states:

actual_status	Meaning
null	Instance is being provisioned
"loading"	Docker image is downloading
"running"	Ready to use

Poll every 10 seconds. Boot time is typically 1–5 minutes depending on the Docker image size. You can also use the onstart script to send a callback when the instance is ready, instead of polling.

This endpoint returns extensive instance details (hardware specs, pricing, networking, utilization metrics, and more). See the Show Instance endpoint for the full field reference.

Once actual_status is "running", you’re ready to connect. Since we set runtype to ssh_direct in step 4, this is a direct connection to the machine.

6. Connect via SSH

Use the ssh_host and ssh_port from the status response to connect directly to your new instance:

ssh root@SSH_HOST -p SSH_PORT

7. Copy Data

With SSH access, you can transfer files using any standard tool — scp, rsync, rclone, etc. For example:

# Upload to instance
rsync -avz -e "ssh -p SSH_PORT" ./data/ root@SSH_HOST:/workspace/data/

# Download from instance
rsync -avz -e "ssh -p SSH_PORT" root@SSH_HOST:/workspace/results/ ./results/

For cloud storage syncing and instance-to-instance transfers, see the data movement guide.

8. Clean Up

When you’re done, destroy the instance to stop all billing.

Alternatively, to pause an instance temporarily instead of destroying it, you can stop it. Stopping halts compute billing but disk storage charges continue.

Destroy (removes everything):

cURL

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  -X DELETE \
  "https://console.vast.ai/api/v0/instances/INSTANCE_ID/"

Stop (pauses compute, disk charges continue):

cURL

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"state": "stopped"}' \
  "https://console.vast.ai/api/v0/instances/INSTANCE_ID/"

Both return {"success": true}.

Next Steps

You’ve now completed the full instance lifecycle through the API: authentication, search, creation, polling, and teardown. From here:

• SSH setup — See the SSH guide for key configuration and advanced connection options.
• Use templates — Avoid repeating image and config parameters on every create call. The Templates API guide covers creating, sharing, and launching from templates.