API reference

Terminate instance

Permanently destroys an instance and its storage.

This cannot be undone. The instance moves TERMINATING → TERMINATED and can never be started again. Use POST /instances/{id}/stop if you only want to pause billing.

Terminating one that is STOPPING is accepted; the stop does not have to settle first.

Terminating one that is already TERMINATING is also accepted, and re-issues the teardown. That is the way to recover a termination that failed part-way. It is not a safe blind retry, though: once the underlying resource is actually gone, a further call returns 500 until the instance settles at TERMINATED. Poll GET /instances/{id} rather than retrying on a timer.

Returns 409 only when the instance is already TERMINATED.

POST

instances

{id}

terminate

Terminate an instance

curl --request POST \
  --url https://api.hivecompute.ai/v1/instances/{id}/terminate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason_note": "scaling down overnight"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason_note: 'scaling down overnight'})
};

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

import requests

url = "https://api.hivecompute.ai/v1/instances/{id}/terminate"

payload = { "reason_note": "scaling down overnight" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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>"
}

{
  "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": "FORBIDDEN",
    "message": "You do not have access to this resource.",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found.",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The resource is not in a state that allows this action.",
    "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.

Path Parameters

string<uuid>

required

The instance's unique identifier.

Body

application/json

Optional context recorded in the audit trail for this action.

reason_note

string

Free-text note explaining why the action was taken.

Maximum string length: 10000

Example:

"scaling down overnight"

Response

The request was accepted; the instance's current state is returned.

instance_id

string<uuid>

Unique identifier.

name

string

Display name.

Example:

"training-run-4"

status

enum<string>

Current lifecycle state.

Available options:

CREATED,

DEPLOYED,

STARTING,

RUNNING,

ERRORED,

TERMINATING,

TERMINATED,

STOPPING,

STOPPED

region

string

The datacenter location the instance runs in, which is narrower than a region: a region contains several locations.

This value cannot be passed back as the region filter on GET /instances or GET /presets — those take a region code from GET /regions (FR), not a location (france-2). Filtering on a location returns an empty page rather than an error.

Example:

"france-2"

gpu_type

string

GPU model.

Example:

"RTX 4090"

size

string

Headline shape of the instance, as a count and a unit rather than a preset name. Use GET /presets to resolve the full hardware.

Example:

"8 x GPU"

cpu_count

integer

Virtual CPUs allocated.

resources

string

Human-readable summary of the allocated hardware.

bandwidth

number

Allocated bandwidth, in Mbps.

storage_used_gb

number

Disk provisioned for the instance, in GB. Not a measure of use.

hourly_rate

number

Price charged per hour while running, in credits.

current_cost

number

Total spend accrued over the instance's life, in credits. Currently identical to total_cost_incurred; it is not scoped to the current run.

total_cost_incurred

number

Total cost over the instance's whole life, in credits.

total_runtime_hours

number

Total hours the instance has spent running.

ttl_remaining_hours

number

Credit runway in hours, computed across the whole organisation rather than for this instance, so every instance in an org reports the same figure.

started_at

string<date-time> | null

When the instance last entered RUNNING.

terminated_at

string<date-time> | null

When the instance was terminated, if it has been.

termination_reason

string | null

Why the instance was terminated, if it has been.

guest_ready

string

Whether the guest OS has finished booting and is reachable.

guest_ready_reason

string | null

Explanation when the guest is not ready.

⌘I

Terminate an instance

curl --request POST \
  --url https://api.hivecompute.ai/v1/instances/{id}/terminate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason_note": "scaling down overnight"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason_note: 'scaling down overnight'})
};

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

import requests

url = "https://api.hivecompute.ai/v1/instances/{id}/terminate"

payload = { "reason_note": "scaling down overnight" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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>"
}

{
  "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": "FORBIDDEN",
    "message": "You do not have access to this resource.",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found.",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The resource is not in a state that allows this action.",
    "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"
  }
}