Skip to content

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:

json
[
  {
    "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:

json
[
  {
    "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

json
{
  "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:

VariableDefault
DPPAN_RANK_TPS_WEIGHT1.0Multiplier on throughput (the numerator). Raise it to favour faster nodes more aggressively
DPPAN_RANK_LATENCY_WEIGHT1.0Multiplier 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

json
{
  "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

json
{ "node_id": "550e8400-e29b-41d4-a716-446655440000", "warnings": [] }

POST /nodes/join ​

Auto-registration: orchestrator assigns the layer range based on available VRAM.

Request body

json
{
  "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

json
{
  "node_id":    "550e8400-e29b-41d4-a716-446655440000",
  "start_layer": 0,
  "end_layer":   8,
  "warnings":   []
}
CodeMeaning
409node_id already registered
422Architecture mismatch or unknown model
503No layer range available (all layers covered)

POST /nodes/:id/health ​

Node heartbeat — updates metrics counters.

Request body (all fields optional)

json
{
  "tokens_generated": 100,
  "requests_served":  5,
  "errors":           0,
  "avg_latency_ms":   42.0,
  "peak_vram_mb":     4096
}

Response 200

json
{ "ok": true }

GET /nodes/:id/hardware ​

Hardware profile reported by the node.

Response 200

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{ "ok": true }

Response 403 if invalid.

POST /admin/nodes/:id/reassign ​

Change the layer range a node is responsible for.

Request body

json
{ "start_layer": 0, "end_layer": 8 }

Response 200

json
{ "ok": true, "node_id": "...", "start_layer": 0, "end_layer": 8 }

PATCH /admin/nodes/:id/state ​

Override node state.

Request body

json
{ "state": "ready" }

state values: "ready" · "idle"

Response 200

json
{ "ok": true, "node_id": "...", "state": "Ready" }

DELETE /admin/nodes/:id/force ​

Force-deregister a node (admin override — does not notify the node).

Response 200

json
{ "ok": true, "node_id": "..." }

Free to run · Proprietary