Uptime: Wiki

Parameters

Path Parameters

id*integer

Entity id

Formatint64

Range0 <= value

Code example

curl -X GET "https://example.com/api/v1/hosts/0"

Response example

{  "id": 0,  "display_name": "string",  "display_name_plain": "string",  "rack_id": 0,  "az_id": 0,  "start_u": 0,  "u_size": 0,  "sku_name": "string",  "arch": "string",  "accelerator": "string",  "label": "string",  "visual": {    "status": "Idle",    "indicator": "Off",    "fan": "Off",    "port": {      "link": "Down",      "active": true    },    "accelerator_glow": 0.1  },  "unit_count": 0,  "stranded_unit_count": 0,  "online": true,  "powered": true,  "power_feeds": 0,  "mem_requested_pct": 0.1,  "cpu_requested_pct": 0.1,  "ssd_used_pct": 0.1,  "wear_factor": 0.1,  "iops_actual": 0,  "iops_capacity": 0,  "nic_count": 0,  "ports": [    {      "index": 0,      "label": "string",      "link": "Down",      "active": true,      "cable_ids": [        0      ],      "peer": null,      "port_id": 0,      "state": "string",      "media": "string",      "gbps_tx": 0.1,      "gbps_rx": 0.1,      "link_capacity_gbps": 0,      "error_count": 0,      "bytes_egress_total": 0,      "bytes_ingress_total": 0,      "link_flaps": 0,      "cable_able": true,      "connector": "string",      "color": "string",      "breakout_used_gbps": 0,      "breakout_capacity_gbps": 0,      "breakout_leg_count": 0    }  ],  "egress_gbps": 0.1,  "ingress_gbps": 0.1,  "served_customer_ids": [    0  ],  "inv_status": "string",  "age_hours": 0,  "power_on_hours": 0,  "condition_pct": 0,  "mtbf_hours": 0,  "resale_dollars": 0.1,  "pool_id": 0,  "service_classes": [    "string"  ],  "vgpu_slices_total": 0,  "vgpu_slices_used": 0,  "gpu_mem_mb_total": 0,  "gpu_mem_mb_used": 0,  "nic_module_slots": 0,  "nic_modules_installed": 0,  "free_vcpu_milli": 0,  "free_mem_mb": 0,  "free_ssd_gb": 0,  "free_ssd_iops": 0,  "physical_vcpu": 0,  "physical_mem_mb": 0,  "physical_ssd_gb": 0,  "allocated_millivcpu": 0,  "used_millivcpu": 0,  "overcommit_target": 0.1,  "overcommit_max": 0.1,  "contention_state": "string",  "monthly_cost_direct_dollars": 0.1,  "monthly_cost_facility_dollars": 0.1,  "monthly_cost_total_dollars": 0.1,  "facility_basis": 0.1}

Response body

200The entity

application/json

id*integer

Formatint32

Range0 <= value

display_name?string

Player-facing identity like srv-01. Unique per host; survives SKU upgrades and moves. Prefer this over sku_name when labelling the host in UI — sku_name is the model designation, shared across many hosts.

display_name_plain?string

Plain-mode counterpart: server 1 vs srv-01. Two-voice per [[two_voice_labels_2026]]. Empty on legacy saves; clients should fall back to display_name.

rack_id*integer

Formatint32

Range0 <= value

az_id*integer

Formatint32

Range0 <= value

start_u*integer

Starting U slot inside the rack.

Formatint32

Range0 <= value

u_size*integer

Formatint32

Range0 <= value

sku_name*string

arch*string

accelerator?string|null

label*string

visual*

unit_count?integer

EVERY placed unit on this host, all seven service classes — the generic occupancy, straight off sim_engine::placement::UnitIndex. Includes STRANDED units (their last known host is still the only place they claim); [HostView::stranded_unit_count] is that subset, so unit_count - stranded_unit_count is what is actually running.

This is the only per-host workload count. It replaced vm_count, which counted VM-substrate units alone — plain VMs plus managed-DB copies — so a host carrying only CDN POPs, Kubernetes workers, LB proxies, object shards or function containers read 0, and every consumer inherited that hole: the capacity lens' Load column, the netview host subtitle and the host status LED all showed "empty" on a fleet running CDN / Kubernetes / object storage.

vm_count was kept alongside for one release purely because it had shipped, and was DELETED at PROTOCOL_VERSION 47: no reader wanted it. Every live client site was already spelled unit_count with a vm_count fallback. Do not reintroduce a VM-substrate-only per-host count; if one is ever genuinely needed it belongs behind a name that says substrate, not workload.

Formatint32

Range0 <= value

stranded_unit_count?integer

Stranded units still pinned to this host — allocations whose customer is Single tier and whose host has lost reachability while remaining powered up. Drives the diegetic inspector's "N stranded" line. 0 when nothing is stranded on this host. Defaulted via serde for old saves.

GENERIC since 2026-08-10: a stranded shard, worker or POP counts here too. Was stranded_vm_count; renamed at PROTOCOL_VERSION 47 with the rest of the vm_-named generic fields.

Formatint32

Range0 <= value

online?boolean

Whether the host is up on the network right now — powered on AND reachable through a live uplink chain (engine host_is_serviceable). The honest "online/offline" signal: a host that's cabled but whose uplink chain is down reads false, unlike a naive "any cable attached" check. Defaulted via serde for old / partial payloads.

powered?boolean

At least one AC cord seated (or none required — wall rack, unracked, or cord-free scenario). False = the box is dark until the player plugs it in. Mirrors engine Host.powered.

power_feeds?integer

Connected AC cord count (0..=psu_count). >= 2 = PSU-failure resilience at redundant_psu_overhead_w extra draw per extra cord.

Formatint32

Range0 <= value

mem_requested_pct*number

REQUESTED (reserved/committed) share, NOT live usage: numerator is vm_used_* + service_reserved_*, denominator NAMEPLATE sku.*. Live demand rides used_millivcpu on this same struct — the two answer different questions, hence the explicit requested in the name.

Formatfloat

cpu_requested_pct*number

Formatfloat

ssd_used_pct*number

Formatfloat

wear_factor?number

Wear multiplier on nameplate capacity (eff_millivcpu = sku.vcpu * wear_factor). Shipped because without it a client reading this streamed view CANNOT compute the wear-adjusted EFFECTIVE basis at all — it has nameplate and nothing else. That gap is why some surfaces divide by nameplate and others by effective. 1.0 = pristine.

Formatfloat

iops_actual*integer

Formatint32

Range0 <= value

iops_capacity*integer

Formatint32

Range0 <= value

nic_count?integer

Physical NIC port count. T1-T2 SKUs are single-NIC; T3+ ship multi-NIC for LACP redundancy. Defaulted via serde.

Formatint32

Range0 <= value

ports?array<>

Per-NIC readouts — same content as RackInspectSnapshot's host occupant ports. Populated for every host so the workbench inspector can show speed / state / activity per NIC.

egress_gbps?number

Smoothed network egress in Gbps for this host's link cable. Accumulated across the customer's full service mix on this host (Functions, VMs, ManagedDb, ObjectStore, LB, CDN, K8s). Drives per-port throughput at the cable's host-end + the switch port the cable lands on.

Formatdouble

ingress_gbps?number

Smoothed ingress (data flowing IN — request bodies, PUT uploads). Surfaced separately so the inspector can show asymmetric flows ("↑ heavy / ↓ light") accurately.

Formatdouble

served_customer_ids?array<>

Customers whose workload currently has presence on this host — VM allocations, in-flight Function invocations, ManagedDb primaries, K8s nodes. Sourced from engine allocation maps; the inspector filters its tenant list to this set when scoped to a single host. Order: customer id ascending (deterministic).

inv_status?string

Lifecycle status — "Mounted" / "Carried" / "Loose" / "SellQueued". Renderer dispatches off this for inventory presentation (e.g. a Loose host renders at its cubby, not its start_u).

age_hours?integer

Wall-clock age in hours since first install.

Formatint32

Range0 <= value

power_on_hours?integer

Powered-on hours accumulated.

Formatint32

Range0 <= value

condition_pct?integer

Condition 0..=100 against SKU MTBF.

Formatint32

Range0 <= value

mtbf_hours?integer

SKU MTBF in hours — surfaced so the inspector can show "120k expected, 18k used" without re-resolving the catalog.

Formatint32

Range0 <= value

resale_dollars?number

Resale value at current condition + age. Same value the engine credits if the item is sold right now.

Formatdouble

pool_id?integer

Host-pool membership. 0 ⇒ the General pool (Host.pool_id == None); otherwise the HostPoolView.id this host belongs to. Delta-encoded — only changes when the player reassigns the host, so it costs nothing per tick at rest. Resolve the name via WorldSnapshot.host_pools.

Formatint32

Range0 <= value

service_classes?array<string>

Service-class tags this host serves a data-plane agent for (service plane). Lets the Services page list a service's allocated hosts exactly rather than approximating via served-customer overlap. Empty when the model is off. Small (0–3 tags); changes rarely.

vgpu_slices_total?integer

Total vGPU slices this host's SKU exposes across all its physical GPUs (HostSku::total_vgpu().0). 0 for a non-GPU host. Pairs with vgpu_slices_used for the inspector's GPU partition gauge.

Formatint32

Range0 <= value

vgpu_slices_used?integer

vGPU slices currently reserved by placed VMs (Host.vgpu_slices_used).

Formatint32

Range0 <= value

gpu_mem_mb_total?integer

Total GPU frame-buffer (MB) across all physical GPUs (HostSku::total_vgpu().1). 0 for a non-GPU host.

Formatint32

Range0 <= value

gpu_mem_mb_used?integer

GPU frame-buffer (MB) currently reserved (Host.gpu_mem_used_mb).

Formatint32

Range0 <= value

nic_module_slots?integer

Rear cages that accept a purchasable SFP NIC module (HostSku.module_slots). 0 = the chassis takes no modules.

Formatint32

Range0 <= value

nic_modules_installed?integer

NIC modules currently installed (Host.nic_modules.len()), bounded by nic_module_slots.

Formatint32

Range0 <= value

free_vcpu_milli?integer

Absolute free vCPU in millicores (Host::free_millivcpu()), i.e. effective capacity minus VM + service-reserved usage. Mirrors the exact accessor migrate_vm gates on, so the migration picker can offer only hosts a specific VM footprint actually fits.

Formatint64

Range0 <= value

free_mem_mb?integer

Absolute free memory in MB (Host::free_mb()). Same accessor as the migrate_vm capacity gate.

Formatint64

Range0 <= value

free_ssd_gb?integer

Absolute free SSD in GB (Host::free_ssd_gb()). Same accessor as the migrate_vm capacity gate.

Formatint64

Range0 <= value

free_ssd_iops?integer

Absolute free SSD IOPS headroom (Host::free_ssd_iops()). Same accessor as the migrate_vm capacity gate; lets the picker match the engine's IOPS check for block-backed VMs.

Formatint64

Range0 <= value

physical_vcpu?integer

Physical vCPU count exposed by this host's SKU (HostSku::vcpu). The denominator for the overcommit ratio; allocated_millivcpu may exceed physical_vcpu * 1000 when the host is oversubscribed.

Formatint32

Range0 <= value

physical_mem_mb?integer

Nameplate memory in MB (HostSku::mem_mb) — the twin of physical_vcpu, and the denominator mem_requested_pct divides by. Shipped because this view exposed a nameplate total for CPU and none for memory, so a consumer had to reconstruct total RAM from free_mem_mb and mem_requested_pct (UG-320). Memory never decays, so this is constant for the life of the host.

Formatint32

Range0 <= value

physical_ssd_gb?integer

Nameplate disk in GB (HostSku::ssd_gb), same rationale as physical_mem_mb. Also constant for life — wear scales IOPS, not formatted capacity, so free_ssd_gb subtracts from exactly this. Note free_ssd_iops does NOT: IOPS is the one wear-adjusted axis, so its free figure is against a ceiling that falls as the host ages.

Formatint32

Range0 <= value

allocated_millivcpu?integer

Sum of vCPU (in millicores) allocated to placed VMs on this host (Host::committed_millivcpu). This is the promised/reserved figure, not the live demand — compare against physical_vcpu * 1000 to show the oversubscription fill.

Formatint64

Range0 <= value

used_millivcpu?integer

Live vCPU demand in millicores (Host::used_millivcpu_demand()), i.e. what the workloads are actually asking for this tick. Compared against eff_millivcpu (physical × overcommit_target) to derive the contention state.

Formatint64

Range0 <= value

overcommit_target?number

Player-dialed overcommit target for this host (Host::overcommit_target). 1.0 = strictly 1:1 (dedicated); higher permits oversubscription up to overcommit_max.

Formatdouble

overcommit_max?number

Hard ceiling on overcommit_target (config.tuning.vcpu_overcommit_max). Clamps the player-facing slider.

Formatdouble

contention_state?string

Contention read-out: "healthy" (demand well under effective capacity), "warm" (demand > ~0.8× effective), "contended" (demand exceeds effective capacity — VMs are being throttled). Drives the host console's green/amber/red contention indicator.

monthly_cost_direct_dollars?number

C6.3 — monthly cost caused by this box directly: power draw, its own depreciation share, maintenance (HostCost::direct).

Formatdouble

monthly_cost_facility_dollars?number

This box's share of the shared facility plant — rent, WAN circuits, cable opex, peering, network gear and their depreciation (HostCost::facility_share). Allocated by RACK UNITS, because floor space is what rent buys and a 4U chassis occupies four times the site a 1U does. Zero for a host that is not racked: a box on the floor serves no tenant and consumes no site capacity the fleet is paying for.

Formatdouble

monthly_cost_total_dollars?number

direct + facility_share — the host's all-in monthly cost (HostCost::total).

Formatdouble

facility_basis?number

The rack-U fraction that produced monthly_cost_facility_dollars (HostCost::facility_basis). 0.0 when not racked. Surfaced so the console can EXPLAIN the facility line rather than assert it.

Formatdouble

Host

Parameters

Try the endpoint

Code example

Response example

Response body

On this page