Nodes, metrics and admin API
Base URL and authentication are on the REST API overview.
Nodes
GET /nodes
List all registered nodes.
Response 200 — array of NodeRecord:
[
{
"node_id": "550e8400-e29b-41d4-a716-446655440000",
"model_id": "llama3.2:1b",
"http_url": "http://192.168.1.20:5001",
"grpc_url": "http://192.168.1.20:5002",
"start_layer": 0,
"end_layer": 8,
"state": "Ready",
"vram_mb": 8192,
"tokens_total": 1024,
"requests_served": 12,
"avg_latency_ms": 45.2,
"uptime_s": 3600
}
]state values: Ready · Degraded · Dead · Joining
GET /nodes/visual
The nodes offering image and video models (dppan join --visual), and what each offers. A node serving a text model as well is also in GET /nodes.
Response 200:
[
{
"node_id": "f39fd5ca-99fe-4acc-af7f-ccd7730beac1",
"node_name": "metal-studio-mac",
"device": "metal",
"version": "0.8.5",
"hardware": { "cpu_model": "Apple M4 Pro", "cpu_cores": 14, "ram_total_mb": 24576,
"disk_free_gb": 310, "os": "macOS 26.3" },
"connected_at": "2026-10-12T09:14:22.981Z",
"models": [
{ "id": "z-image-turbo", "kind": "image", "size_bytes": 6549431936 },
{ "id": "wan2.1-vace-1.3b-fast", "kind": "video", "size_bytes": 10737418240 }
]
}
]GET /nodes/rankings
Nodes ranked by combined score (throughput, latency, VRAM).
Response 200
{
"rankings": [
{ "node_id": "...", "model_id": "llama3.2:1b", "score": 0.92, "rank": 1 }
]
}The formula weights throughput against latency, and both weights are tunable on the orchestrator:
| Variable | Default | |
|---|---|---|
DPPAN_RANK_TPS_WEIGHT | 1.0 | Multiplier on throughput (the numerator). Raise it to favour faster nodes more aggressively |
DPPAN_RANK_LATENCY_WEIGHT | 1.0 | Multiplier on latency (the denominator). Set below 1.0 to de-emphasise latency |
Both default to 1.0, so out of the box throughput and latency carry equal weight. They affect ranking only — a node that ranks last is still eligible for work.
POST /nodes
Explicit node registration with caller-provided layer range. Used by legacy (--legacy) mode.
Request body
{
"node_id": "550e8400-e29b-41d4-a716-446655440000",
"model_id": "llama3.2:1b",
"http_url": "http://192.168.1.20:5001",
"grpc_url": "http://192.168.1.20:5002",
"start_layer": 0,
"end_layer": 8,
"n_total_layers": 16,
"d_model": 2048,
"vram_mb": 8192,
"hardware": { "gpu": "metal", "device_name": "Apple M4 Pro", "vram_mb": 32768 },
"capabilities": [
{ "model_id": "llama3.2:1b", "n_layers": 16, "d_model": 2048 }
]
}Response 200
{ "node_id": "550e8400-e29b-41d4-a716-446655440000", "warnings": [] }POST /nodes/join
Auto-registration: orchestrator assigns the layer range based on available VRAM.
Request body
{
"node_id": "550e8400-e29b-41d4-a716-446655440000",
"model_id": "llama3.2:1b",
"http_url": "http://192.168.1.20:5001",
"grpc_url": "http://192.168.1.20:5002",
"n_total_layers": 16,
"d_model": 2048,
"vram_mb": 8192,
"layers": "0-8",
"hardware": { "gpu": "metal", "device_name": "Apple M4 Pro", "vram_mb": 32768 },
"capabilities": []
}layers is optional — omit to let the orchestrator assign.
Response 200
{
"node_id": "550e8400-e29b-41d4-a716-446655440000",
"start_layer": 0,
"end_layer": 8,
"warnings": []
}| Code | Meaning |
|---|---|
409 | node_id already registered |
422 | Architecture mismatch or unknown model |
503 | No layer range available (all layers covered) |
POST /nodes/:id/health
Node heartbeat — updates metrics counters.
Request body (all fields optional)
{
"tokens_generated": 100,
"requests_served": 5,
"errors": 0,
"avg_latency_ms": 42.0,
"peak_vram_mb": 4096
}Response 200
{ "ok": true }GET /nodes/:id/hardware
Hardware profile reported by the node.
Response 200
{
"gpu": "metal",
"device_name": "Apple M4 Pro",
"vram_mb": 32768
}GET /nodes/:id/metrics
A node's recent metrics: the last ~60 samples, 10 s apart.
Response 200
{
"node_id": "...",
"samples": [
{ "tps": 45.2, "latency_ms": 22.1, "ts_ms": 1745123456000 }
]
}DELETE /nodes/:id
Deregister a node (node-initiated clean exit).
Response 204 — no body
Metrics
GET /metrics/summary
Cluster-wide aggregate metrics.
Response 200
{
"total_nodes": 2,
"ready_nodes": 2,
"total_tokens": 50000,
"total_requests": 200,
"avg_latency_ms": 38.5
}GET /metrics/model/:model_id
Per-model metrics.
Response 200
{
"model_id": "llama3.2:1b",
"nodes": 2,
"requests": 150,
"tokens": 30000,
"avg_latency_ms": 35.0
}GET /metrics/history
Historical request rate (last N minutes, 1-minute buckets).
Response 200
{
"buckets": [
{ "ts_ms": 1745123400000, "requests": 12, "tokens": 4800 }
]
}GET /metrics/generations
Image and video jobs over a time range: where they ran, how they ended, and how many were sent in each part of the range. Only the caller's own jobs are counted, as GET /v1/generations lists them; a deployment with sign-in answers a request without a session with 401. No prompt or model is returned. A job that never started is not counted.
Query — range: 1h, 24h (default), 7d or 30d. The buckets are 5 minutes, 1 hour, 6 hours and 1 day long.
Response 200
{
"range": "24h",
"bucket_seconds": 3600,
"places": [
{ "place": "this machine", "node": false, "jobs": 6, "completed": 5, "failed": 0,
"cancelled": 1, "running": 0, "avg_seconds": 112.4, "last_at": "2026-10-15T07:43:02Z" },
{ "place": "studio-mac", "node": true, "jobs": 4, "completed": 3, "failed": 1,
"cancelled": 0, "running": 0, "avg_seconds": 186.0, "last_at": "2026-10-15T07:37:23Z" }
],
"history": [
{ "ts": 1760509200000, "jobs": { "this machine": 2, "studio-mac": 1 } }
]
}place is this machine for the orchestrator's own jobs, or the node's name. avg_seconds is the mean time from start to end of the completed jobs, null when none completed. history has every bucket from the start of the range to now, an empty one with "jobs": {}. An unknown range answers 400.
Admin Endpoints
All admin routes require X-Admin-Token: <token>.
GET /admin/verify
Check token validity.
Response 200
{ "ok": true }Response 403 if invalid.
POST /admin/nodes/:id/reassign
Change the layer range a node is responsible for.
Request body
{ "start_layer": 0, "end_layer": 8 }Response 200
{ "ok": true, "node_id": "...", "start_layer": 0, "end_layer": 8 }PATCH /admin/nodes/:id/state
Override node state.
Request body
{ "state": "ready" }state values: "ready" · "idle"
Response 200
{ "ok": true, "node_id": "...", "state": "Ready" }DELETE /admin/nodes/:id/force
Force-deregister a node (admin override — does not notify the node).
Response 200
{ "ok": true, "node_id": "..." }