Instances

An instance is a virtual server. These endpoints list, inspect, update, and power them. We provision customer instances through billing orders for server packages. Power actions are asynchronous and return a workflow.

Search instances

GET/v1/workspaces/{wid}/instancesSearch instances

Lists the instances in a workspace with pagination. Use sort=id&dir=desc for newest first.

Path parameters

Name	Type	Description
wid	string	Workspace ID

Query parameters

Name	Type	Description
q	string	Quick search by name, IP address, or ID
ip	string	Filter by a public or private IP address
id	string[]	Filter to specific instance IDs
name	string	Filter by name
node	string[]	Filter by node ID
sku	string[]	Filter by product code
iso	string[]	Filter by attached ISO ID
online	boolean	Only online, or only offline, instances
state	string[]	PENDING, AVAILABLE, FAILED, SUSPENDED, DELETING, UNPLACED
boot	string	DISK or ISO
terminating	boolean	Filter by whether termination is scheduled
backup_plan	string[]	Filter by backup plan ID
region	string	NA_01
vpc	string[]	Filter by VPC ID
os	string	WINDOWS, LINUX, or BSD
owner	string[]	Filter by workspace ID

All query parameters are optional. Plus the shared pagination parameters. Returns 200 OK with KeysetResultEnrichedInstanceListViewInstanceLive, containing items, has_next, has_previous, limit, page, total, and nullable after and before cursors. Each item includes live online state.

Create an instance

We create servers with POST /v1/workspaces/{wid}/orders. See Place an order for package selection, request fields, payment collection, and the 200 OK response. See Create a server for a provisioning example.

Remove an instance

We remove delivered servers with POST /v1/subjects/{sid}/cancel. Read the instance's subject ID, then follow Cancel a purchase. This returns 200 OK with SubjectView and stops billing. For an undelivered purchase, follow Cancel an order.

Fetch an instance

GET/v1/instances/{iid}Fetch instance detail

Path parameters

Name	Type	Description
iid	string	Instance ID, required

Returns 200 OK with EnrichedInstanceDetailViewInstanceLive, including details, networking, state, live online state, and the nullable billing subject ID.

Update an instance

PATCH/v1/instances/{iid}Update instance settings

Updates instance settings. The request body is required. Every field is optional. Send only what you are changing.

Path parameters

Name	Type	Description
iid	string	Instance ID, required

Request body

Field	Type	Description
name	string	Name and hostname, letters, digits, and hyphens in dot-separated labels, at most 63 characters
boot	string	Boot target, DISK or ISO
uefi	boolean	Boot with UEFI firmware
secure_boot	boolean	Enable Secure Boot
attach_virtio_cd	boolean	Attach the VirtIO drivers CD
sync_hostname	boolean	Keep the guest hostname in sync with the name
user_cloudinit	string or null	Cloud-init user data, or null to clear it
disable_cloudinit	boolean	Disable vendor cloud-init features
os_name	string or null	OS display name, for example Ubuntu 24.04, or null to clear it

Returns 200 OK with the updated EnrichedInstanceDetailViewInstanceLive.

Power an instance

POST/v1/instances/{iid}/powerIssue a power action

Issues a power action. Responds 202 Accepted with a workflow.

Path parameters

Name	Type	Description
iid	string	Instance ID, required

Request body

Field	Type	Required	Description
action	string	yes	One of POWER_ON, POWER_OFF, SHUTDOWN, POWER_CYCLE. POWER_CYCLE is the hard reboot the panel labels Reboot.

curl -X POST https://api.galaxygate.net/v1/instances/101/power \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "POWER_CYCLE" }'

To power several instances in one call, see batch power. Returns a workflow.

Fetch instance metrics

GET/v1/metricsFetch instance metrics

Returns time-series metrics (CPU, memory, disk, network) for one instance over a window. Each series has its own unit.

Query parameters

Name	Type	Required	Description
instance	string	yes	Instance ID
start	integer	yes	Window start, non-negative Unix seconds
end	integer	yes	Window end, non-negative Unix seconds
step	integer	yes	Resolution in seconds (minimum 15)

Returns 200 OK with InstanceMetrics: cpu, memory, disk_reads, disk_writes, disk_total, disk_used, network_incoming, network_outgoing, bandwidth_incoming_bytes, and bandwidth_outgoing_bytes.

CPU usage is a percentage where 100 means one full core. Memory and filesystem usage are bytes. Disk throughput is KiB/s and network throughput is bytes per second. The bandwidth totals integrate traffic over the requested window. Guest memory and filesystem series can be empty when the guest agent is unavailable.