Uptime: Wiki | Customer

Parameters

Path Parameters

id*integer

Entity id

Formatint64

Range0 <= value

Code example

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

Response example

{  "id": 0,  "name": "string",  "archetype": "string",  "tier": "string",  "kind_label": "string",  "lifecycle": "string",  "pending_until_ns": 0,  "health": 0.1,  "block_quality": 0.1,  "revenue_total_dollars": 0.1,  "revenue_last_hour_dollars": 0.1,  "availability_pct": 0.1,  "p99_latency_ms": 0,  "p99_recent_ms": 0,  "cpu_load_pct": 0.1,  "latency_top_term": "string",  "p50_latency_ms": 0,  "rps": 0.1,  "failed_requests_lifetime": 0,  "total_requests_lifetime": 0,  "failed_last_hour": 0,  "sla_p99_budget_ms": 0,  "in_latency_spike": true,  "on_probation": true,  "sla_credits_dollars": 0.1,  "egress_gbps": 0.1,  "ingress_gbps": 0.1,  "service_kinds": [    "string"  ],  "stranded_unit_count": 0,  "unit_count": 0,  "distinct_hosts": 0,  "max_units_on_host": 0,  "satisfaction": 0.1,  "satisfaction_label": "string",  "under_attack": true,  "attack_class": "string",  "breached": true,  "services": [    {      "class_tag": "string",      "label": "string",      "requested_count": 0,      "provisioned_count": 0,      "gap": 0,      "vcpu": 0,      "memory_mb": 0,      "accelerator": "string",      "durability": "string",      "region_id": 0,      "state": "string",      "reason": "string",      "state_tag": "string",      "reason_tag": "string",      "placement": {        "code": "string",        "unit": "string",        "subject": "string",        "needed": 0,        "available": 0,        "shortfall": 0,        "considered": 0,        "candidates": 0      },      "replication_tag": "string",      "replicas_held": 0,      "replicas_target": 0    }  ],  "detail_omitted": true,  "provisioned_total": 0,  "requested_total": 0,  "compliance_required": "string",  "required_arch": "string",  "requires_multi_az": true,  "requires_private_segment": true,  "demands_audit_logs": true,  "demands_air_gap": true,  "required_region": 0,  "requires_gpu": true,  "gpu_slices_demand": 0,  "growth_ceiling_vms": 0,  "requires_dedicated_hosts": true,  "requires_uncontended": true,  "requires_dedicated": true,  "eviction_fee_dollars": 0.1,  "requirements_unmet_mask": 0,  "requires_fault_isolation": true,  "sla_period_availability_frac": 0.1,  "sla_period_seconds_over_latency": 0.1,  "sla_period_elapsed_seconds": 0.1,  "margin_revenue_dollars": 0.1,  "margin_cost_dollars": 0.1,  "margin_dollars": 0.1,  "cost_infrastructure_dollars": 0.1,  "cost_transit_dollars": 0.1,  "service_margins": [    {      "service": "string",      "revenue_dollars": 0.1,      "cost_dollars": 0.1,      "margin_dollars": 0.1    }  ]}

Response body

200The entity

application/json

id*integer

Formatint32

Range0 <= value

name*string

archetype*string

tier*string

kind_label*string

lifecycle*string

pending_until_ns?|

Formatint64

Range0 <= value

health*number

Formatdouble

block_quality*number

Formatdouble

revenue_total_dollars*number

Formatdouble

revenue_last_hour_dollars*number

Formatdouble

availability_pct*number

Formatdouble

p99_latency_ms?|

p99 request latency over the LONG window (CustomerState::latency, tuning.latency_window_capacity samples at one per sim second, so roughly the worst 10 samples of the last ~16.7 sim minutes). This is the figure the SLA is measured against — sla_p99_budget_ms compares to THIS, and the engine's breach/credit path reads the same window — so it is deliberately sticky and must never be relabelled "now". Pair it with p99_recent_ms for the responsive figure.

Formatdouble

p99_recent_ms?|

p99 request latency over the SHORT window (CustomerState::latency_recent, tuning.latency_recent_capacity samples, ~2 sim minutes) — cached by the engine once per metrics tick as CustomerState::recent_p99_ms, which is also what the incident anomaly machine opens and recovers on.

This is the "right now" number. The long window above pins one spike for up to ~16 sim minutes, which read to players as "customers returning to normal latency taking ages" while the incident had already closed. Both ship so the readout can be honest about which is which: current vs the window the SLA is actually scored on.

None until the first metrics tick after load (load_reported clears the cached value because it describes a window that no longer exists). Whole milliseconds — the engine caches it as u64 ms and re-deriving it here would mean a clone+sort of the window per customer per snapshot.

Formatdouble

cpu_load_pct*number

Offered CPU as a percentage of what this tenant CONTRACTED, uncapped, so it reads past 100 when they are asking for more than they rent.

This is the number that explains a latency spike on hosts that look idle. A VM queues on its OWN vCPU ceiling, and the queue curve bites from queue_util_knee (70%) upward: 25 ms at 95%, 168 ms at 99%, ~1990 ms at the clamp. Host utilisation is a DIFFERENT quantity and does not move with it, which is why a player checking the host map after a p99 spike finds nothing wrong (player report, Mateo Bank 2026-07-28). 0 when the tenant has no placed VMs.

Formatfloat

latency_top_term*string

Pre-rendered dominant latency term, e.g. "queue 940.2 ms (94%)", or empty when nothing has been sampled yet.

The engine already attributes latency across serve floor / fabric / queue / CPU contention / attack / backbone / hairpin / cold start and ranks them, but that breakdown only ever reached the INCIDENT card. The customer panel is where a player asks "why is this tenant slow", so the leading term belongs here too. Formatted render-side because the client has no business re-deriving shares.

p50_latency_ms?|

Median (p50) request latency in milliseconds — the "typical" number players read as "how's this customer doing", distinct from the p99 tail. Float, so lightly-loaded customers don't all collapse to the same whole-ms value. None until the window has samples.

Formatdouble

rps?number

Smoothed requests per second across this customer's workloads. Mirrors CustomerState.rps. Drives the inspector's "Acme Co. — 4 req/s" plain-English read.

Formatdouble

failed_requests_lifetime?integer

Cumulative failed-request count across the customer's services (AvailabilityStats.requests_failed).

Formatint64

Range0 <= value

total_requests_lifetime?integer

Total request count across the same window. Pairs with failed_requests_lifetime to compute the recent failure rate.

Formatint64

Range0 <= value

failed_last_hour?integer

Failed requests since the last hourly snapshot — the delta the inspector reads as "12 errors this hour." Reset by the engine each hour boundary (failed_at_hour_snapshot).

Formatint64

Range0 <= value

sla_p99_budget_ms?|

Latency-budget tier — milliseconds the customer's SLA tolerates at p99. None for Bronze (no latency budget).

Formatint64

Range0 <= value

in_latency_spike?boolean

True when the customer is currently in a sustained latency spike (engine edge-trigger). Drives an SLA-breach pill in the inspector.

on_probation?boolean

True when the customer is on probation — engine flag for "they're seriously considering churn." The renderer can show this with an at-risk pill.

sla_credits_dollars?number

SLA-breach credits accumulated this billing period (issued back to the customer; net negative for the provider). Lifetime sum.

Formatdouble

egress_gbps?number

Smoothed bandwidth attributed to this customer across their service mix. Egress = response bodies / GET fan-out / etc.; ingress = request bodies / PUT uploads / replication writes. Real workloads are asymmetric (image hosting = egress-heavy; backup ingest = ingress-heavy) and surfacing both reflects that.

Formatdouble

ingress_gbps?number

Formatdouble

service_kinds?array<string>

Short-code service mix: subset of {"fn", "vm", "obj", "lb", "db", "cdn", "k8s"} for the services this customer runs. Used by the dashboard's Services drilldown to count tenants per service kind and by the customer wall to render service-kind chips.

stranded_unit_count?integer

Stranded VMs this customer owns — pinned to an unreachable host with no auto-failover. Drives the red "N VMs stranded" badge on the ops-console customer row and the comms-panel incident card's [Migrate] quick-action.

Formatint32

Range0 <= value

unit_count?integer

VM placement spread — the anti-affinity story made legible. vm_count total VMs this customer runs; vm_distinct_hosts how many separate chassis they're spread across; vm_max_on_host the most this customer has on any single host (the worst-case "one machine dies" blast radius). Anti-affinity raises distinct_hosts and lowers max_on_host; bin-packing does the opposite.

Formatint32

Range0 <= value

distinct_hosts?integer

Formatint32

Range0 <= value

max_units_on_host?integer

Formatint32

Range0 <= value

satisfaction?number

Composite customer satisfaction in 0.0..=1.0 — folds health, relationship trust, and long-term sentiment into one player-facing "how's this relationship" number (see CustomerState::satisfaction).

Formatdouble

satisfaction_label?string

Plain-words band for satisfaction (Delighted / Happy / Content / Unsettled / At risk).

under_attack?boolean

True when a malicious attack is currently landing on THIS tenant — the named victim of a targeted flood, or anyone the per-tenant impact pass is failing requests for. Drives the "UNDER ATTACK" risk pill so the player sees which tenant an attack is hurting, not just a fleet-wide board.

attack_class?string

The attack class hitting this tenant (Flood / Connection flood / App flood / Break-in attempts), empty when not under attack — for the pill caption.

breached?boolean

True while this tenant is in a BREACHED state — a sustained, unmitigated intrusion compromised them. Drives the "BREACHED" risk pill; distinct from (and more severe than) an availability incident.

services?array<>

Per-service demand-vs-fulfilment breakdown — one entry per service this customer is contracted for. Item 5 / Phase 5 of tasks/service_health_incidents_rework_2026_07.md: makes the gap between what a customer asked for and what's actually live legible everywhere, instead of only inferable from a health percentage. Reads Engine::service_probe for state/reason (Phase 1's spine) so this view never re-derives feasibility/placement math.

Populated only when this session asked for THIS customer's detail (Request::SubscribeCustomer), or for any reader that did not ask at all — the HTTP API mirror, the TUI and tests all project at CustomerDetail::All. A game session carries it for the tenant whose console is open and nobody else. Read detail_omitted, never services.is_empty(), to tell "not sent" from "has no services".

It is the expensive half of the section: services plus service_margins is ~28% of the customers bytes, and the customers section is 57.2% of a realistic baseline once the comms work landed.

detail_omitted?boolean

true when services and service_margins were WITHHELD from this session rather than being genuinely empty.

Same rule, and the same reason, as ChannelView::is_preview: a reader that infers "this tenant has no services" from an empty vector draws an empty console for a tenant with a full estate, and the failure is silent. A customer really can have zero priced services, so the vector's emptiness cannot carry this.

provisioned_total?integer

Units this tenant has PLACED, summed across every service class.

Always sent, whatever detail_omitted says. It is the roster's entire need from services (customers_view.gd sums provisioned_count and requested_count over the vector for its capacity-shortfall badge), so shipping two integers lets the list keep working while the array it used to walk stays behind the subscription.

Formatint32

Range0 <= value

requested_total?integer

Units this tenant CONTRACTED for, summed across every service class. The other half of the roster's shortfall badge; see provisioned_total.

Formatint32

Range0 <= value

compliance_required?string

Compliance regime the customer's contract requires (SOC2/HIPAA/PCI), or "None". Mirrors ProspectView.compliance_required.

required_arch?string

Raw CPU-arch requirement tag ("x86_64"/"riscv"/…) or "" if agnostic.

requires_multi_az?boolean

requires_private_segment?boolean

demands_audit_logs?boolean

demands_air_gap?boolean

required_region?|

Data-residency region the contract pins to, if any.

Formatint32

Range0 <= value

requires_gpu?boolean

gpu_slices_demand?integer

Formatint32

Range0 <= value

growth_ceiling_vms?integer

Plateau — the max VM count this persona compounds to (0 = unknown/none).

Formatint32

Range0 <= value

requires_dedicated_hosts?boolean

True when the customer's contract demands its private network on DEDICATED, homed hosts (single-tenant iron) — the 4× isolation tier vs 2× for a plain private network. Implies requires_private_segment; the detail pane shows one combined chip. Mirrors ProspectView post-accept.

requires_uncontended?boolean

True when the customer's archetype contracts UNCONTENDED (1:1 CPU) — its workloads run on hosts admitted to an uncontended segment (1:1, no overcommit). A CPU guarantee, wholly independent of dedication/tenancy and anti-affinity spread. Mirrors ProspectView.requires_uncontended; drives the detail "Uncontended CPU (guaranteed 1:1)" requirement chip.

requires_dedicated?boolean

True when the customer's archetype contracts DEDICATED, single-tenant hosts (private iron, no co-tenants). Tenancy guarantee, not a CPU one — distinct from uncontended. Mirrors ProspectView.requires_dedicated; drives the detail "Dedicated host (private)" requirement chip.

eviction_fee_dollars?number

Termination fee (dollars) the operator would pay to evict this customer right now — the tier's eviction_penalty_frac of one month's run-rate (decoupled from the SLA-outage refund), plus any unused prepay on a still-active Reserved contract (capped), clamped to current cash. Shown on the Evict action so the player sees the bill before arming it.

Formatdouble

requirements_unmet_mask?integer

Bitmask of the customer's ASKED contract requirements that are currently UNMET, so the always-on requirement chips render met (green) vs unmet (amber) instead of alarm-amber for every ask. Stable wire bit layout: bit 0 = multi-AZ, 1 = private-segment/dedicated, 2 = data-residency, 3 = fault-isolation (spread). Derived from Engine::unmet_requirements; 0 = every asked requirement is satisfied (or none is asked). A chip is MET when its requirement is asked (the existing demand bools) and its bit is clear.

Formatint32

Range0 <= value

requires_fault_isolation?boolean

True when the contract ASKS for fault isolation — copies of the tenant's workloads kept off a shared fault domain (redundancy tier > 1 host replica, or an archetype that requires anti-affinity). This is the ASK side of requirements_unmet_mask bit 3; without it a client can render the spread chip UNMET but never MET, because the mask alone cannot distinguish "asked and satisfied" from "never asked". Mirrors ProspectView.requires_fault_isolation.

sla_period_availability_frac?number

SLA accrual, billing-period model (PROTOCOL 32) — the availability fraction accrued THIS billing period (since CustomerState::sla_period_start), 1 - failed/total over sla_period_requests_{total,failed}. Guards divide-by-zero: 1.0 (nothing to fault yet) when no requests have accrued this period. This is the EXACT figure Engine::settle_sla_period compares against SlaTier::availability_target() at period close — distinct from availability_pct above (the recovering rolling EWMA read for the health headline, not what the bill is judged on). Surfaced so a credit on the bill is explainable instead of appearing from nowhere (see memory/billing_authority_design_2026_07_27.md).

Formatdouble

sla_period_seconds_over_latency?number

Seconds accrued THIS billing period where the short-window p99 (p99_recent_ms) sat over the tier's sla_p99_budget_ms — mirrors CustomerState::sla_period_seconds_over_latency. Always 0 for Bronze (no latency budget, never accrues). Pair with sla_period_elapsed_seconds to get the fraction SlaTier::latency_penalty_band bands (2% / 10% / 30% thresholds).

Formatdouble

sla_period_elapsed_seconds?number

Sim-seconds elapsed since this billing period started accruing (CustomerState::sla_period_start to now) — the denominator for sla_period_seconds_over_latency, so the client can render "over budget N% of the period" instead of a bare seconds count.

Formatdouble

margin_revenue_dollars?number

Steady-state MONTHLY revenue for this tenant's live contract — GrossMargin::revenue, i.e. meter_projected + rate, the same pair that quotes a prospect. NOT an accumulator: pairing it with revenue_total_dollars (lifetime) would compare two different months.

Formatdouble

margin_cost_dollars?number

Monthly cost honestly attributable to this tenant — GrossMargin::attributable_cost. Their share of the hosts they occupy (including those hosts' rack-U share of the facility) plus the upstream transit bought for their bytes. Excludes overhead BY CONSTRUCTION; see CustomersSummary::overhead_dollars.

Formatdouble

margin_dollars?number

margin_revenue_dollars - margin_cost_dollars. GROSS margin. Negative means the tenant loses money before a single dollar of payroll.

Formatdouble

cost_infrastructure_dollars?number

The infrastructure half of margin_cost_dollars (TenantCost:: infrastructure) — host share incl. facility.

Formatdouble

cost_transit_dollars?number

The transit half of margin_cost_dollars (TenantCost::transit) — upstream bytes. The one cost that arrives already per-customer.

Formatdouble

service_margins?array<>

Per-service revenue/cost/margin split, ServiceClass::ALL order, zero rows omitted (GrossMargin::by_service). Empty until the tenant has a priced service.

Customer

Parameters

Try the endpoint

Code example

Response example

Response body

On this page