Skip to content
Fuse
Esc
↑↓navigate↵open⌘Jpreview

Fetch a host by ID

GET/v1/hosts/{hostId}
Authorization
AuthorizationBearer token · headerrequired
`Authorization: Bearer <token>` — either the static master token (`ORCH_AUTH_TOKEN`) or a revocable API key issued via /v1/api-keys (API keys require Postgres; without a database only the master token is accepted). Master-only surfaces (exec, attach, API key management) refuse API keys with 403. **Authentication can be disabled entirely.** When neither `ORCH_AUTH_TOKEN` nor an API key store (`DATABASE_URL`) is configured — the default local-development posture — the bearer middleware becomes a pass-through: every operation this document marks as secured is reachable with no credentials, requests carry no principal, and master-only surfaces therefore admit everyone. Never run that configuration on a reachable network; set `ORCH_REQUIRE_AUTH=true` to make the orchestrator refuse to start without a master token.
or
fuse_sessionAPI key · cookierequired
HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.
Path parameters
hostIdstringrequired
Host identifier assigned by the caller.
Responses
200Host.
idstringrequired
urlstringrequired
regionstring
statestringrequired
`draining` means cordoned with eviction pending; drain automation is not yet implemented.
Allowed:activecordoneddraining
backendstring
Virtualization backend the host runs.
Allowed:firecrackerqemu
labelsobject
Operator-declared placement labels for this host.
capacityHostCapacityrequired
On responses (HostInfo.capacity / HostInfo.allocated) the four scalar fields cpus/ram_mb/storage_gb/vm_count are always serialized. On registration requests only vm_count is required; the other scalars may be omitted to have them probed from the host agent.
Show properties
cpusinteger
ram_mbinteger
storage_gbinteger
vm_countintegerrequired
Max concurrent VMs.
gpusinteger
Count of whole GPU devices. Only qemu-backed hosts may report a non-zero value.
gpu_kindstring
GPU model (e.g. "a100"). Empty when gpus is 0.
mig_profilesobject
Fractional GPU capacity: MIG instance count by profile name (e.g. {"1g.10gb": 4}). Requires backend "qemu". Independent of the whole-device gpus counter (decision D5). Keys are lowercased on registration and must be mig-parted profile names (e.g. "1g.10gb") with positive counts; invalid entries are rejected with 400.
gpu_devicesGPUDevice[]
Per-device GPU inventory probed from the host agent. Probe-only: values sent in a register request are discarded. Populated only on capacity (never allocated) of qemu-backed hosts. `gpus` and the length of `gpu_devices` may disagree: the host agent emits at most one entry per IOMMU group, so a group holding several GPUs contributes one entry while each card still counts toward `gpus`. Treat `gpus` as the schedulable count and `gpu_devices` as best-effort detail.
Show properties
Array of GPUDevice
uuidstring
modelstring
E.g. "NVIDIA A100-SXM4-40GB".
pci_bus_idstring
memory_mbinteger
driver_versionstring
cuda_versionstring
Reserved — not currently populated by the host agent.
compute_capstring
mig_capableboolean
mig_modestring
E.g. "Enabled".
iommu_groupstring
Reserved — not currently populated by the host agent.
allocatedHostCapacityrequired
On responses (HostInfo.capacity / HostInfo.allocated) the four scalar fields cpus/ram_mb/storage_gb/vm_count are always serialized. On registration requests only vm_count is required; the other scalars may be omitted to have them probed from the host agent.
Show properties
cpusinteger
ram_mbinteger
storage_gbinteger
vm_countintegerrequired
Max concurrent VMs.
gpusinteger
Count of whole GPU devices. Only qemu-backed hosts may report a non-zero value.
gpu_kindstring
GPU model (e.g. "a100"). Empty when gpus is 0.
mig_profilesobject
Fractional GPU capacity: MIG instance count by profile name (e.g. {"1g.10gb": 4}). Requires backend "qemu". Independent of the whole-device gpus counter (decision D5). Keys are lowercased on registration and must be mig-parted profile names (e.g. "1g.10gb") with positive counts; invalid entries are rejected with 400.
gpu_devicesGPUDevice[]
Per-device GPU inventory probed from the host agent. Probe-only: values sent in a register request are discarded. Populated only on capacity (never allocated) of qemu-backed hosts. `gpus` and the length of `gpu_devices` may disagree: the host agent emits at most one entry per IOMMU group, so a group holding several GPUs contributes one entry while each card still counts toward `gpus`. Treat `gpus` as the schedulable count and `gpu_devices` as best-effort detail.
Show properties
Array of GPUDevice
uuidstring
modelstring
E.g. "NVIDIA A100-SXM4-40GB".
pci_bus_idstring
memory_mbinteger
driver_versionstring
cuda_versionstring
Reserved — not currently populated by the host agent.
compute_capstring
mig_capableboolean
mig_modestring
E.g. "Enabled".
iommu_groupstring
Reserved — not currently populated by the host agent.
last_seenstring<date-time>required
created_atstring<date-time>required
updated_atstring<date-time>required
warningsstring[]
Non-fatal registration notices (e.g. a declared capacity value that exceeded what was probed from the host agent). Only ever populated on the response to POST /v1/hosts.
404Resource does not exist. Note the distinct code `route_not_found`, returned when the URL matches no registered route at all (wrong host, port, or path prefix) rather than a known route with a missing resource.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
Request
curl -X GET "http://localhost:8080/v1/hosts/string" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "id": "string",
  "url": "string",
  "region": "string",
  "state": "active",
  "backend": "firecracker",
  "labels": {},
  "capacity": {
    "cpus": 0,
    "ram_mb": 0,
    "storage_gb": 0,
    "vm_count": 0,
    "gpus": 0,
    "gpu_kind": "string",
    "mig_profiles": {},
    "gpu_devices": [
      {
        "uuid": "string",
        "model": "string",
        "pci_bus_id": "string",
        "memory_mb": 0,
        "driver_version": "string",
        "cuda_version": "string",
        "compute_cap": "string",
        "mig_capable": true,
        "mig_mode": "string",
        "iommu_group": "string"
      }
    ]
  },
  "allocated": {
    "cpus": 0,
    "ram_mb": 0,
    "storage_gb": 0,
    "vm_count": 0,
    "gpus": 0,
    "gpu_kind": "string",
    "mig_profiles": {},
    "gpu_devices": [
      {
        "uuid": "string",
        "model": "string",
        "pci_bus_id": "string",
        "memory_mb": 0,
        "driver_version": "string",
        "cuda_version": "string",
        "compute_cap": "string",
        "mig_capable": true,
        "mig_mode": "string",
        "iommu_group": "string"
      }
    ]
  },
  "last_seen": "2024-01-01T00:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "warnings": [
    "string"
  ]
}