List instances

GET

instances

List your instances

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

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

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

{
  "data": [
    {
      "instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "training-run-4",
      "region": "france-2",
      "gpu_type": "RTX 4090",
      "size": "8 x GPU",
      "cpu_count": 123,
      "resources": "<string>",
      "bandwidth": 123,
      "storage_used_gb": 123,
      "hourly_rate": 123,
      "current_cost": 123,
      "total_cost_incurred": 123,
      "total_runtime_hours": 123,
      "ttl_remaining_hours": 123,
      "started_at": "2023-11-07T05:31:56Z",
      "terminated_at": "2023-11-07T05:31:56Z",
      "termination_reason": "<string>",
      "guest_ready": "<string>",
      "guest_ready_reason": "<string>"
    }
  ],
  "pagination": {
    "next": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNy0yOSJ9",
    "size": 50
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "[{\"property\":\"size\",\"constraints\":[\"size must not be greater than 200\"]}]",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API token",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Too Many Requests",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred.",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Authorizations

Authorization

string

header

required

An API key issued by Hive Compute support. See Authentication above for how to request one.

Query Parameters

cursor

string

Opaque cursor from a previous response's pagination.next. Omit to start at the first page.

size

integer

default:50

Number of items per page.

Required range: 1 <= x <= 200

status

enum<string>

Return only instances in this state.

Each value is a bucket covering the transitional states that lead into it, so an instance is always matched by exactly one of them:

running — also matches CREATED, DEPLOYED and STARTING
stopped — also matches STOPPING
terminated — also matches TERMINATING
errored — ERRORED only

There is no filter for a transitional state on its own. Read status on each instance to tell them apart.

Available options:

running,

stopped,

terminated,

errored

region

enum<string>

Return only instances in this region. Use a name from GET /regions.

An unrecognised value is not an error: it matches nothing and returns an empty page. Note this is not the same vocabulary as the region field on an instance, which carries the datacenter location — see the Instance schema.

Available options:

UAE,

FR,

US

gpu_type

string

Return only instances on this GPU model, e.g. RTX 4090.

date_range_begin

string<date-time>

Return only instances that started at or after this ISO 8601 timestamp. Despite the name, the bound is on started_at, not on creation time.

An instance that never started running has no started_at, so it is excluded as soon as either bound is set — including a range wide enough to cover everything. Omit both bounds to see those instances.

date_range_end

string<date-time>

Return only instances that started at or before this ISO 8601 timestamp. The same started_at semantics as date_range_begin, including the exclusion of instances that never started.

free_text_search

string

Match against instance name, instance id and host.

Maximum string length: 255

sort_field

enum<string>

Field to order by. Defaults to creation time, newest first.

Available options:

NAME,

GPU_TYPE,

SIZE,

REGION,

HOURLY_RATE,

CURRENT_COST,

STATUS

sort_direction

enum<string>

Order direction, applied to sort_field. Defaults to ASC.

It is ignored unless sort_field is also set: with no sort field the result keeps its default order and this parameter has no effect.

Available options:

ASC,

DESC

Response

A page of instances.

data

object[]

Show child attributes

pagination

object

Cursor pagination metadata.

Show child attributes

⌘I

List your instances

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

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

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

{
  "data": [
    {
      "instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "training-run-4",
      "region": "france-2",
      "gpu_type": "RTX 4090",
      "size": "8 x GPU",
      "cpu_count": 123,
      "resources": "<string>",
      "bandwidth": 123,
      "storage_used_gb": 123,
      "hourly_rate": 123,
      "current_cost": 123,
      "total_cost_incurred": 123,
      "total_runtime_hours": 123,
      "ttl_remaining_hours": 123,
      "started_at": "2023-11-07T05:31:56Z",
      "terminated_at": "2023-11-07T05:31:56Z",
      "termination_reason": "<string>",
      "guest_ready": "<string>",
      "guest_ready_reason": "<string>"
    }
  ],
  "pagination": {
    "next": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNy0yOSJ9",
    "size": 50
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "[{\"property\":\"size\",\"constraints\":[\"size must not be greater than 200\"]}]",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API token",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Too Many Requests",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred.",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Public API

API reference

Authorizations

Query Parameters

Response