Model, health, and metrics inspection¶
GET /v1/models¶
Returns the configured model in OpenAI list format:
{
"object": "list",
"data": [
{
"id": "example/model",
"object": "model",
"owned_by": "narwhal"
}
]
}
GET /health¶
Returns HTTP 200 in every router state.
| Field | Meaning |
|---|---|
status |
Router state |
instances |
Configured fleet size |
available_instances |
Engines eligible for placement |
The earliest matching row sets status:
status |
Meaning |
|---|---|
ok |
Router admits new client requests |
fenced |
Failover block set by a failed lease renewal, a blocked takeover, or an invalid active-router lease |
maintenance |
Whole-wave drain, recovery, or restart hold |
standby |
Standby router |
degraded |
Degraded engine monitoring, pending engine identity validation, or zero engines eligible for placement |
GET /ready¶
Returns HTTP 200 when this router controls the fleet and admits new work.
Returns HTTP 503 with Retry-After: 1 otherwise.
| Field | Meaning |
|---|---|
status |
ready or not_ready |
control_ready |
true when this router controls the fleet and /narwhal/state reports monitoring.degraded as false |
epoch |
Lease epoch |
holder |
Lease-holder token |
reason |
Cause of not_ready, empty when status is ready |
The earliest matching row sets reason:
| Cause | reason |
|---|---|
| Fencing or lease-storage failure | Failover block, such as lease renewal failed |
| Whole-wave hold | whole-wave drain <id>, whole-wave recovery <id>, or whole-wave restart required: <cause> |
| Engine-monitoring degradation | monitoring degraded: <stage> <class> |
| Standby state | shadowing |
| Expired lease | lease expired |
| Pending engine identity validation | engine identity validation pending |
| Zero engines eligible for placement | no available engines |
monitoring.degraded turns true after controller.monitor_failure_limit consecutive failed passes. One fully successful pass sets it back to false.
A standby router counts each control_ready: false response from the active router's /ready as a missed takeover probe.
With zero eligible engines, the response is:
{
"status": "not_ready",
"control_ready": true,
"epoch": 0,
"holder": "",
"reason": "no available engines"
}
During a whole-wave hold, completion requests return HTTP 503 with error code standby.
GET /metrics¶
Returns the Narwhal metrics in Prometheus exposition format 0.0.4.
GET /narwhal/targets¶
Returns one Prometheus HTTP service discovery target group per configured engine. The target is the host and port of the engine's url. The labels carry the engine's iid, the fleet's engine.backend, the scheme of the url, and its path followed by /metrics:
[
{
"targets": ["node0:8000"],
"labels": {
"iid": "n0",
"backend": "vllm",
"__scheme__": "http",
"__metrics_path__": "/metrics"
}
}
]
The engines job of the monitoring stack reads this route every 15 seconds.