Skip to main content
GET
/
api
/
v1
/
instances
show instances
curl --request GET \
  --url https://console.vast.ai/api/v1/instances/ \
  --header 'Authorization: Bearer <token>'
{
  "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": []
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.vast.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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.