> ## 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.

# vastai show instances-v1

Show instances with pagination and filtering (v1).

## Usage

```bash theme={null}
vastai show instances-v1 [OPTIONS]
```

## Options

<ParamField path="-q" type="boolean">
  Only print instance IDs, one per line (alias: `--quiet`)
</ParamField>

<ParamField path="-v" type="boolean">
  Show additional columns (SSH, location, template, etc.) (alias: `--verbose`)
</ParamField>

<ParamField path="-a" type="boolean">
  Fetch all pages automatically and send to pager (alias: `--all`)
</ParamField>

<ParamField path="--status" type="string">
  Filter by container status. Choices: `running`, `loading`, `exited`
</ParamField>

<ParamField path="--label" type="string">
  Filter by instance label; pass empty string to match unlabeled
</ParamField>

<ParamField path="--gpu-name" type="string">
  Filter by GPU model name (e.g. `RTX A5000`)
</ParamField>

<ParamField path="--verification" type="string">
  Filter by machine verification. Choices: `verified`, `unverified`, `deverified`
</ParamField>

<ParamField path="--limit" type="integer">
  Max instances per page (1-25, default 25)
</ParamField>

<ParamField path="--next-token" type="string">
  Resume from a pagination token from a previous page
</ParamField>

<ParamField path="--order-by" type="string">
  Sort column with optional direction, e.g. `start_date desc`
</ParamField>

<ParamField path="--cols" type="string">
  Override displayed columns with a comma-separated list
</ParamField>

## Description

Returns a paginated list of instance objects. Key status fields per instance:

**actual\_status**, current container state:

| Value       | Meaning                                                                  |
| ----------- | ------------------------------------------------------------------------ |
| `null`      | Instance is being provisioned                                            |
| `loading`   | Docker image is downloading or container is starting up                  |
| `running`   | Container is actively executing. GPU charges apply.                      |
| `stopped`   | Container is halted. Disk charges continue; no GPU charges.              |
| `frozen`    | Container is paused with memory preserved. GPU charges apply.            |
| `exited`    | Container process exited unexpectedly                                    |
| `rebooting` | Container is restarting (transient)                                      |
| `unknown`   | No recent heartbeat from the host                                        |
| `offline`   | Host machine disconnected from Vast servers (computed, not stored in DB) |

**intended\_status**, user's desired target state: `running`, `stopped`, or `frozen`.

**cur\_state**, machine contract / hardware allocation state: `running`, `stopped`, or `unloaded` (released on destroy).

**status\_msg**, human-readable detail on the current status.

## Examples

```bash theme={null}
vastai show instances-v1

vastai show instances-v1 --status running --limit 10

vastai show instances-v1 --all --verbose

vastai show instances-v1 --next-token <token_from_previous_page>
```

## Global Options

The following options are available for all commands:

| Option          | Description                                           |
| --------------- | ----------------------------------------------------- |
| `--url URL`     | Server REST API URL                                   |
| `--retry N`     | Retry limit                                           |
| `--raw`         | Output machine-readable JSON                          |
| `--explain`     | Verbose explanation of API calls                      |
| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |