Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
API ReferenceComputeVMs

Get a VM with its GPUs, node, template and price

Returns a VM's full record: its shape and disk, SSH connection details and readiness, GPU model and VRAM, node, OS template, and its hourly rate.

Required permission

Requires the compute.read permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl vms detail get <id>

Guided workflow: orl vms ssh

orl vms ssh <vm-id> [ssh args...] [flags]
GET
/v1/vms/{id}/detail

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Path Parameters

id*string

Response Body

The VM detail

application/json
  1. response
id*string
organizationId*string
name*string
status*string
statusReason?string

Cause of the current status; see VmSummary.statusReason for the machine-readable values.

provisioningStage?string
gpuModelId?string
gpuCount*integer
resourceSize*string
guestMemMb?integer

Guest RAM (MiB) this VM is running with, stamped at placement. Absent on a VM that has never been placed.

guestVcpu?integer

Guest vCPU this VM is running with, stamped by the same placement write as guestMemMb.

requestedGuestMemMb?integer

Guest RAM (MiB) this VM asked for, or the value auto resolved to at admission. Placement honours it, so a co-tenant landing afterwards cannot shrink the VM below it. The exception is the node the VM's disk lives on: when a stopped VM is started, or re-dispatched after its job is lost, and that node's per-GPU share times gpuCount is below this value, and that share still clears the floorPerGpu RAM times gpuCount, the VM starts at the share and this field is updated to it.

tier*string
diskSizeGb*integer
diskUsedBytes?integer
Formatint64
diskTotalBytes?integer
Formatint64
imageUrl?string
capabilityTier?string

compute-fabric capability tier (e.g. "pod"); empty for a plain VM

computeClass?string

compute-fabric purchase option (on_demand; pods created before the rename carry the legacy reserved or interruptible values); empty for a plain VM

containerPort?integer
endpointUrl?string
public?boolean

true = open endpoint (no data-plane auth); false = require an org API key

healthy*boolean
nodeId?string
internalIp?string
sshPort?integer
persistentDiskPath?string
startedAt?string
terminatedAt?string

RFC3339 time the VM was terminated. Set only once status is "terminated" (a stopped/failed VM can restart, so it has none); absent while the VM is live. On a terminated VM, healthy is false and provisioningStage is absent.

createdAt*string
updatedAt*string
osType?string
nonBillable?boolean

This VM's usage is recorded but never charged: a provider org consuming GPUs on a node it owns under its own reservation. pricePerHourCents still reports the real rate (the measurement is kept, the charge is waived) so a client showing a rate MUST also show this or it will display a bill that never arrives.

pricePerHourCents?integer

bundled hourly rate. When the VM has an open usage session this is the rate LOCKED at session open (what settlement charges); otherwise the rate a session WOULD lock: the fabric admission snapshot for a pod, else the current catalog rate for the VM's shape.

sshHost?string

data-plane SSH gateway host, e.g. ssh.run.openrelay.inc

sshHandle?string

RunPod-style SSH handle (first label of endpointUrl); used as the SSH username

sshUser?string

login user the gateway lands as inside the VM (e.g. ubuntu)

sshCommand?string

ready-to-paste ssh command (ssh @)

sshReady?boolean

true when SSH should work now. Observed: a node-side probe saw the guest sshd answer. Falls back to the running-status guess on nodes not yet reporting probes (sshState=unverified).

sshState?string

why sshReady is what it is. booting = the VM is running but its guest OS has not started sshd yet (GPU VMs take minutes); unverified = no probe signal for this node, sshReady is a guess; offline = the VM is not running.

Value in"ready""booting""unverified""offline"
sshStateReason?string

human-readable explanation of sshState, safe to show to the customer

serviceType?string

managed-service tag; empty for a plain VM

hostDiskFreeGb?integer

pods only: free disk on the pod's host node, shared across the pods on that node. Pods have no per-pod quota, and pod storage does not persist across terminate. Absent when the node reports no live disk signal.

hostDiskTotalGb?integer

pods only: total disk on the pod's host node, shared across the pods on that node. Pods have no per-pod quota, and pod storage does not persist across terminate. Absent when the node reports no live disk signal.

volumeGb?integer

pods only: size in GB of the pod's persistent volume at volumeMountPath. Absent on a pod created before volumes existed.

volumeMountPath?string

pods only: where the persistent volume is mounted inside the container (/workspace).

volumeUsedBytes?integer

pods only: bytes the volume currently holds, as of volumeUsedAt (the node reports daily). Absent until the node has reported.

Formatint64
volumeUsedAt?string

pods only: RFC3339 time of the volumeUsedBytes report.

interruptedAt?string

RFC3339 time the workload became interrupted. Cleared when it recovers; kept on a workload that was stopped or deleted because of the interruption.

gpuInfo?
nodeInfo?
templateInfo?
Example Request
curl -X GET 'https://api.openrelay.inc/v1/vms/string/detail'
Example Response
{  "id": "string",  "organizationId": "string",  "name": "string",  "status": "string",  "statusReason": "string",  "provisioningStage": "string",  "gpuModelId": "string",  "gpuCount": 0,  "resourceSize": "string",  "guestMemMb": 0,  "guestVcpu": 0,  "requestedGuestMemMb": 0,  "tier": "string",  "diskSizeGb": 0,  "diskUsedBytes": 0,  "diskTotalBytes": 0,  "imageUrl": "string",  "capabilityTier": "string",  "computeClass": "string",  "containerPort": 0,  "endpointUrl": "string",  "public": true,  "healthy": true,  "nodeId": "string",  "internalIp": "string",  "sshPort": 0,  "persistentDiskPath": "string",  "startedAt": "string",  "terminatedAt": "string",  "createdAt": "string",  "updatedAt": "string",  "osType": "string",  "nonBillable": true,  "pricePerHourCents": 0,  "sshHost": "string",  "sshHandle": "string",  "sshUser": "string",  "sshCommand": "string",  "sshReady": true,  "sshState": "ready",  "sshStateReason": "string",  "serviceType": "string",  "hostDiskFreeGb": 0,  "hostDiskTotalGb": 0,  "volumeGb": 0,  "volumeMountPath": "string",  "volumeUsedBytes": 0,  "volumeUsedAt": "string",  "interruptedAt": "string",  "gpuInfo": {    "name": "string",    "manufacturer": "string",    "vramGb": 0,    "pricePerHourCents": 0  },  "nodeInfo": {    "hostname": "string",    "location": "string"  },  "templateInfo": {    "name": "string",    "osType": "string",    "osVersion": "string"  }}