show instances

Retrieve a paginated list of instances for the authenticated user. Supports keyset pagination (max 25 per page), filtering, column selection, and sorting.

CLI Usage: vastai show instances [OPTIONS] [--api-key API_KEY] [--raw]

GET /api/v1/instances

show instances

cURL

curl --request GET \
  --url https://console.vast.ai/api/v1/instances \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://console.vast.ai/api/v1/instances"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://console.vast.ai/api/v1/instances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://console.vast.ai/api/v1/instances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://console.vast.ai/api/v1/instances"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://console.vast.ai/api/v1/instances")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://console.vast.ai/api/v1/instances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

200

{
  "success": true,
  "instances_found": 5,
  "total_instances": 42,
  "label_counts": {
    "ML Training Job": 3,
    "": 2
  },
  "next_token": "eyJ2YWx1ZXMiOiB7ImlkIjogMTIzfX0=",
  "instances": [
    {
      "id": 312,
      "actual_status": "running",
      "cur_state": "running",
      "next_state": "running",
      "intended_status": "running",
      "label": "ML Training Job 2025",
      "template_id": 2048,
      "template_hash_id": "abcde12345",
      "template_name": "Tensorflow GPU Template",
      "image_uuid": "nvidia/cuda:11.0.3-devel-ubuntu18.04",
      "image_args": [
        "bash",
        "-c",
        "apt update; apt install -y wget"
      ],
      "image_runtype": "ssh ssh_direc ssh_proxy",
      "extra_env": [
        [
          "DOG",
          "CAT"
        ],
        [
          "-p 70001:70001",
          "1"
        ]
      ],
      "onstart": "echo 'hello'; echo $DOG;",
      "jupyter_token": "df77e27085bd4b3bd5d9024bdefb9e6df614b27adb0689e9d8f066fce5e01f0c",
      "status_msg": "success, running nvidia/cuda_11.0.3-devel-ubuntu18.04/ssh",
      "public_ipaddr": "192.0.2.45",
      "local_ipaddrs": "10.0.0.5 172.17.0.2",
      "ssh_host": "ssh123.vast.ai",
      "ssh_idx": "6",
      "ssh_port": 10600,
      "machine_dir_ssh_port": 21000,
      "machine_id": 12,
      "start_date": 1668804745.1223178,
      "end_date": 1735689600,
      "uptime_mins": null,
      "duration": 86400,
      "cpu_arch": "amd64",
      "cpu_cores": 4,
      "cpu_cores_effective": 4,
      "cpu_name": "Core™ i5-6500",
      "cpu_ram": 15989,
      "cpu_util": 0,
      "mem_limit": 15.71815424,
      "mem_usage": 0.00996352,
      "vmem_usage": 0.543945,
      "gpu_name": "RTX 4090",
      "gpu_arch": "nvidia",
      "gpu_totalram": 24576,
      "gpu_ram": 24576,
      "gpu_util": 0,
      "gpu_temp": 38.999981,
      "gpu_frac": 1,
      "gpu_lanes": 16,
      "gpu_mem_bw": 1008,
      "bw_nvlink": 0,
      "disk_name": "Samsung SSD 870",
      "disk_space": 10.08,
      "disk_bw": 500,
      "disk_util": 0.05,
      "disk_usage": 0.05,
      "direct_port_count": 1001,
      "direct_port_start": 20000,
      "direct_port_end": 20002,
      "ports": {
        "8888/tcp": [
          {
            "HostIp": "0.0.0.0",
            "HostPort": "8888"
          }
        ],
        "22/tcp": [
          {
            "HostIp": "0.0.0.0",
            "HostPort": "20000"
          }
        ]
      },
      "static_ip": false,
      "geolocation": "California, United States",
      "verification": "verified",
      "rentable": true,
      "host_id": 7,
      "min_bid": 0.296,
      "is_bid": false,
      "dph_base": 0.8,
      "dph_total": 0.8021,
      "dlperf": null,
      "dlperf_per_dphtotal": null,
      "flops_per_dphtotal": 15.41,
      "total_flops": 12.36,
      "score": null,
      "reliability2": 0.9686655,
      "os_version": null,
      "mobo_name": "Z790 Gaming",
      "pci_gen": 4,
      "pcie_bw": 28,
      "num_gpus": 1,
      "webpage": null,
      "search": {
        "gpuCostPerHour": 0.8,
        "diskHour": 0.0021,
        "totalHour": 0.8021,
        "discountTotalHour": 0,
        "discountedTotalPerHour": 0.8013
      },
      "instance": {
        "gpuCostPerHour": 0.8,
        "diskHour": 0.0013,
        "totalHour": 0.8021,
        "discountTotalHour": 0,
        "discountedTotalPerHour": 0.5034
      },
      "storage_cost": 0.15,
      "storage_total_cost": 0.0021,
      "vram_costperhour": 0.0000494,
      "credit_balance": 4792.99,
      "credit_discount": 0.37,
      "credit_discount_max": 0.4,
      "client_run_time": 100000000,
      "host_run_time": 1,
      "external": false,
      "time_remaining": "12 Mon 24 D 16 Hr",
      "time_remaining_isbid": "11 Mon 26 D 6 Hr",
      "country_code": null,
      "volume_info": []
    }
  ]
}

{
  "error": "invalid_request",
  "msg": "Error in query parameters: dph_total is not a valid search key"
}

{
  "success": false,
  "error": "<string>",
  "msg": "<string>"
}

{
  "detail": "API requests too frequent endpoint threshold=1.0"
}

Authorizations

Authorization · string · header · required

API key must be provided in the Authorization header

Query Parameters

limit · integer · default: 25

Instances per page. Default 25, max 25. Values ≤ 0 are treated as 5.

Required range: x <= 25

after_token · string

Keyset pagination cursor from the previous response's next_token. An invalid token returns a 400 error.

order_by · string

JSON array of sort directives, e.g. [{"col":"id","dir":"asc"}]. Valid dir values: asc, desc (anything else treated as asc). id is always appended as a tiebreaker. Invalid column returns 400.

select_cols · string · default: ["*"]

JSON array of column names to return, e.g. ["id","label","actual_status"]. Use ["*"] for all columns (default). Unknown column names are returned as null.

select_filters · string · default: {}

JSON object of column filters. Supported operators: eq, neq, gt, gte, lt, lte, in, notin. Filterable columns: actual_status, gpu_name, verification, id, label, and other columns stored directly on the contract record. Computed fields (e.g. dph_total, num_gpus) are not filterable and return 400.

Response

200

application/json

Paginated list of instances

success · boolean

Example:

true

instances_found · integer

Number of instances returned in this page.

Example:

5

total_instances · integer

Total number of instances matching the filters.

Example:

42

label_counts · object

Count of instances grouped by label. Unlabelled instances are keyed by empty string.

Example:

{ "ML Training Job": 3, "": 2 }

next_token · string | null

Pagination cursor for the next page. null when no more pages.

Example:

"eyJ2YWx1ZXMiOiB7ImlkIjogMTIzfX0="

instances · object[]

List of instance objects.

Show child attributes