Work with instances

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

The current public 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.
`RUNNING`	The instance is running.
`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.

Termination is irreversible. A terminated instance can’t be restarted, and its data is deleted.

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"

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
}

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.

Public API

API reference

Instance lifecycle

List instances

Filter instances

Get one instance

Start an instance

Stop an instance

Terminate an instance

Get instance logs

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

​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

Suggested workflow

Next step