Work with instances

Instances are the main Compute resource exposed by the Compute API. You can list and inspect existing instances, read recent logs, and start, stop, or terminate them.

The Compute API does not create instances. Create new instances in the Compute console, then use the API to inspect or manage them.

Instance lifecycle

Common lifecycle states include:

Status	What it means
`CREATED`	The instance record exists but has not finished scheduling.
`DEPLOYED`	The instance has been scheduled on a host.
`STARTING`	The instance is booting or restarting during a rebuild.
`RUNNING`	The instance has responded over SSH. Applications inside it may still be starting.
`STOPPING`	Shutdown is in progress.
`STOPPED`	The instance is stopped and can be started again.
`ERRORED`	The instance entered an error state.
`TERMINATING`	Permanent termination is in progress.
`TERMINATED`	The instance has been permanently terminated.

Start, stop, and terminate actions are asynchronous. Poll GET /instances/{id} until the instance reaches the expected state.

List instances

Use GET /instances:

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances?size=20" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

The response includes a data array and pagination metadata.

{
  "data": [
    {
      "instance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "my-training-run",
      "status": "RUNNING",
      "gpu_type": "RTX 5090",
      "region": "france-2"
    }
  ],
  "pagination": {
    "next": null,
    "size": 20
  }
}

Filter instances

Supported filters include:

status
gpu_type
region
date_range_begin
date_range_end
free_text_search
supported sort fields and direction

Use one of the accepted region values: UAE, FR, or US. For exact allowed values and limits, use the GET /instances reference.

Get one instance

Use GET /instances/{id} to read the current state of a specific instance.

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

Start an instance

Use POST /instances/{id}/start to start a stopped instance.

curl --request POST \
  --url "https://api.hivecompute.ai/v1/instances/a1b2c3d4-e5f6-7890-abcd-ef1234567890/start" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Content-Type: application/json"

The start endpoint can return 409 Conflict with error code CONFLICT if the instance is terminating or terminated, or if the account does not have enough credit to start it. Check the latest instance state first. If the instance state allows starting, check the account balance before retrying. If no host currently has enough capacity for the instance’s preset, start can return 503 Service Unavailable. Retry with backoff or choose a preset in another region.

Stop an instance

Use POST /instances/{id}/stop to stop a running instance without terminating it.

curl --request POST \
  --url "https://api.hivecompute.ai/v1/instances/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stop" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Content-Type: application/json"

Poll the instance until it reaches STOPPED. The stop endpoint returns 409 Conflict with code CONFLICT if the instance is terminating or already terminated.

Terminate an instance

Use POST /instances/{id}/terminate to permanently terminate an instance.

A terminated instance can’t be restarted, and its local data is deleted. Download important files before terminating it. Support-assisted disk recovery depends on an available backup and is not guaranteed.

curl --request POST \
  --url "https://api.hivecompute.ai/v1/instances/a1b2c3d4-e5f6-7890-abcd-ef1234567890/terminate" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Content-Type: application/json"

The terminate endpoint returns 409 Conflict with code CONFLICT only when the instance is already TERMINATED. If it is STOPPING or TERMINATING, the request is accepted; poll the instance state instead of retrying blindly.

Get instance logs

Use GET /instances/{id}/logs to fetch recent container output.

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logs?lines=100" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

For VM boot or crash issues, contact Support with the instance ID and approximate failure time. Support can review VM serial-console logs; this endpoint documents recent container output. Logs are returned newest first. entries[0] is the most recent line. A shortened response looks like this:

{
  "entries": [
    {
      "timestamp": "2026-08-10T10:02:15Z",
      "line": "Training epoch 2/10 complete. Loss: 0.298"
    },
    {
      "timestamp": "2026-08-10T10:01:00Z",
      "line": "Training epoch 1/10 complete. Loss: 0.342"
    }
  ],
  "line_count": 2
}

Read instance usage metrics

Call GET /instances/{id}/metrics with a required range of 1h, 6h, 24h, or 7d. Use an API key tied to the user who owns the instance. The response includes time series and a status for each metric group. Data availability depends on the instance’s runtime and hardware. Treat missing samples as missing data, rather than zero usage.

Suggested workflow

List your instances

Call GET /instances and find the instance you want to manage.

Check its current state

Call GET /instances/{id} before sending a lifecycle action.

Run the action

Start, stop, or terminate the instance.

Poll for the final state

Call GET /instances/{id} until the instance reaches the expected state.

Next step

Continue with Use pagination and filters.

Guides

API reference

Instance lifecycle

List instances

Filter instances

Get one instance

Start an instance

Stop an instance

Terminate an instance

Get instance logs

Read instance usage metrics

Suggested workflow

Next step

​Instance lifecycle

​List instances

​Filter instances

​Get one instance

​Start an instance

​Stop an instance

​Terminate an instance

​Get instance logs

​Read instance usage metrics

​Suggested workflow

​Next step

Instance lifecycle

List instances

Filter instances

Get one instance

Start an instance

Stop an instance

Terminate an instance

Get instance logs

Read instance usage metrics

Suggested workflow

Next step