Instances

Instances are the legacy virtual machine resources. The unified server model (/v1/servers) is now preferred for both bare metal and virtual machines.

VM-specific endpoints remain under /v1/instances for metrics, events, SSH, and backup operations.

List Instances

GET /v1/instances

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`sort`	string	Sort field: `name`, `status`, `createdAt`, `region`
`status`	string	Filter by status
`provider`	string	Filter by provider ID
`region`	string	Filter by region
`fields[instances]`	string	Comma-separated fields to include

Example:

curl "https://api.fugoku.com/v1/instances?page=1&limit=20&sort=createdAt" \
  -H "Authorization: Bearer $TOKEN"

Get Instance

GET /v1/instances/:id

Create Instance

POST /v1/instances

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Instance name (1-64 chars)
`providerId`	string	Yes	Provider ID
`region`	string	Yes	Region identifier
`instanceType`	string	Yes	Instance type / plan
`workerCount`	integer	No	Number of workers (default: 1)
`image`	string	No	OS image slug
`diskSizeGb`	integer	No	Disk size in GB
`sshKeyId`	string	No	SSH key ID
`spot`	boolean	No	Use spot pricing (default: false)
`ports`	array	No	Port numbers to expose
`autoStopMinutes`	integer	No	Auto-stop after inactivity
`accelerators`	string	No	GPU accelerators (e.g., `A100:1`)
`tags`	object	No	Key-value tags

Example:

curl -X POST https://api.fugoku.com/v1/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-gpu-server",
    "providerId": "prov-1",
    "region": "us-east-1",
    "instanceType": "g3.h100.2x",
    "workerCount": 1,
    "image": "ubuntu-22.04",
    "diskSizeGb": 100,
    "spot": false
  }'

Returns 202 Accepted with instance data and jobId.

Get Instance

GET /v1/instances/:id

Update Instance

PATCH /v1/instances/:id

Request Body:

Field	Type	Required	Description
`name`	string	No	New instance name
`tags`	object	No	Key-value tags

Delete Instance

DELETE /v1/instances/:id

Returns 202 Accepted with jobId. Deletion is asynchronous.

Instance Actions

POST /v1/instances/:id/action

Request Body:

{
  "action": "start | stop | restart | terminate | reinstall | rescue"
}

Supported actions: start, stop, restart, terminate, reinstall, rescue.

Instance Metrics

GET /v1/instances/:id/metrics

Returns CPU, memory, GPU, network, and disk utilization metrics.

Instance Events

GET /v1/instances/:id/events

Returns activity log for the instance.

SSH Connection Info

GET /v1/instances/:id/ssh

Returns host, port, username, and key fingerprint for SSH access.

Instance Job History

GET /v1/instances/:id/jobs

Returns job history for the instance with pagination.

All Instances (Aggregated)

GET /v1/instances/all

Returns all active instances across all enabled providers. Supports ?refresh=true to force live status sync.

Instance Backups

GET /v1/instances/:instanceId/backups
POST /v1/instances/:instanceId/backups

List and create backups for a virtual machine instance.

Status Values

Value	Description
`creating`	Instance is being provisioned
`active`	Running and available
`stopping`	Shutting down
`stopped`	Powered off
`error`	Provisioning or runtime error
`terminated`	Permanently deleted
`terminating`	Deletion in progress
`starting`	Booting up
`provisioning`	Post-creation setup

Instances

On this page