---
title: "show instances"
method: GET
path: "/api/v1/instances/"
tags: ["Instances"]
---

# show instances

`GET /api/v1/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]`

## Query parameters

- `limit` integer
- `after_token` string
- `order_by` string
- `select_cols` string
- `select_filters` string

## Response `200`

Paginated list of instances

- object
  - `success` boolean
  - `instances_found` integer — Number of instances returned in this page.
  - `total_instances` integer — Total number of instances matching the filters.
  - `label_counts` object — Count of instances grouped by label. Unlabelled instances are keyed by empty string.
  - `next_token` string, nullable — Pagination cursor for the next page. `null` when no more pages.
  - `instances` object[] — List of instance objects.
    - `id` integer
    - `actual_status` string, nullable
    - `cur_state` string
    - `next_state` string
    - `intended_status` string
    - `label` string, nullable
    - `template_id` integer, nullable
    - `template_hash_id` string, nullable
    - `template_name` string, nullable
    - `image_uuid` string
    - `image_args` string[]
    - `image_runtype` string
    - `extra_env` array[]
      - string[]
    - `onstart` string
    - `jupyter_token` string
    - `status_msg` string, nullable
    - `public_ipaddr` string
    - `local_ipaddrs` string
    - `ssh_host` string
    - `ssh_idx` string
    - `ssh_port` integer
    - `machine_dir_ssh_port` integer
    - `machine_id` integer
    - `start_date` number, float
    - `end_date` number, float
    - `uptime_mins` number, nullable
    - `duration` number, float
    - `cpu_arch` string
    - `cpu_cores` integer
    - `cpu_cores_effective` number, float
    - `cpu_name` string
    - `cpu_ram` integer
    - `cpu_util` number, float
    - `mem_limit` number, nullable
    - `mem_usage` number, nullable
    - `vmem_usage` number, nullable
    - `gpu_name` string
    - `gpu_arch` string
    - `gpu_totalram` integer
    - `gpu_ram` integer
    - `gpu_util` number, nullable
    - `gpu_temp` number, nullable
    - `gpu_frac` number, float
    - `gpu_lanes` integer
    - `gpu_mem_bw` number, float
    - `bw_nvlink` number, float
    - `disk_name` string
    - `disk_space` number, float
    - `disk_bw` number, float
    - `disk_util` number, float
    - `disk_usage` number, float
    - `direct_port_count` integer
    - `direct_port_start` integer
    - `direct_port_end` integer
    - `ports` object, nullable — Port mappings. Only present on running instances.
    - `static_ip` boolean
    - `geolocation` string
    - `verification` string
    - `rentable` boolean
    - `host_id` integer
    - `min_bid` number, float
    - `is_bid` boolean
    - `dph_base` number, float
    - `dph_total` number, float
    - `dlperf` number, nullable
    - `dlperf_per_dphtotal` number, nullable
    - `flops_per_dphtotal` number, float
    - `total_flops` number, float
    - `score` number, nullable
    - `reliability2` number, float
    - `os_version` string, nullable
    - `mobo_name` string
    - `pci_gen` number, float
    - `pcie_bw` number, float
    - `num_gpus` integer
    - `webpage` string, nullable
    - `search` object
    - `instance` object
    - `storage_cost` number, float
    - `storage_total_cost` number, float
    - `vram_costperhour` number, float
    - `credit_balance` number, nullable
    - `credit_discount` number, nullable
    - `credit_discount_max` number, nullable
    - `client_run_time` number, float
    - `host_run_time` number, float
    - `external` boolean
    - `time_remaining` string
    - `time_remaining_isbid` string
    - `country_code` string, nullable
    - `volume_info` object[]

## Other responses

- `400` — Bad request. Returned for invalid filter column/operator, invalid `order_by` column, or invalid `after_token`.
- `401` — Unauthorized
- `429` — Too Many Requests

---

[API](https://skmtc.net/vast/apis/vast-ai-api.md) · [All operations](https://skmtc.net/vast/apis/vast-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vast/vast-ai-api/revisions/4ed14f79f796/schema)