---
title: "List Instances"
method: GET
path: "/v2/instance"
tags: ["instances"]
---

# List Instances

`GET /v2/instance`

List a registry's instances, optionally including recently terminated ones.

## Query parameters

- `registry_id` string, uuid, required — Filter instances to this registry
- `include_terminated` boolean — Include recently terminated instances
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- ActiveInstancesResponse
  - `instances` ActiveInstance[], required
    - `id` string, uuid, required
    - `registry_id` string, uuid, nullable
    - `build_id` string, uuid, nullable
    - `status` string, required
    - `created_at` string, date-time, required
    - `terminated_at` string, date-time, nullable
    - `public_ip` string, nullable
    - `ec2_instance_type` string, nullable
    - `max_runtime_seconds` integer, nullable
    - `user_name` string, nullable
    - `user_avatar_url` string, nullable
    - `actual_cost` number, nullable
    - `hourly_rate` number, nullable
    - `tier` string, nullable
    - `cpu_millicores` integer, nullable
    - `memory_gb` number, nullable
    - `timeout_seconds` integer, nullable
    - `max_session_seconds` integer, nullable
    - `file_tracking_enabled` boolean, nullable
    - `no_external_access` boolean, nullable
    - `protocol_version` string, nullable
    - `vnc_url` string, nullable
    - `metadata` object, nullable
    - `trace` ActiveInstanceTrace
      - `id` string, uuid, required
      - `status` string, nullable
      - `reward` number, nullable
      - `created_at` string, date-time, required
      - `thumbnail_url` string, nullable
      - `error` string, nullable
  - `total` integer, required
  - `running_count` integer, required
  - `terminated_count` integer, required
  - `has_more` boolean, required

## Other responses

- `400` — Invalid or malformed request
- `401` — Missing or invalid credentials
- `403` — Caller may not access this resource
- `404` — Referenced entity does not exist
- `409` — Resource already exists
- `422` — Validation Error

---

[API](https://skmtc.dev/hud/apis/hud-platform.md) · [All operations](https://skmtc.dev/hud/apis/hud-platform/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hud/hud-platform/revisions/58558fc733d9/schema)