Skip to content
GET /registry/workers

Lists every live session (lease not expired), fleet-wide.

Authentication

pinboard:operator scope. Results are filtered by the claim:

  • A worker's namespaces and envs keep only namespaces inside claims.pinboard.namespaces (and, hostname-aware, whose hostname and env match hostnames and envs).
  • A worker with no namespace left is omitted.

Example

curl https://pinboard.example.com/registry/workers \
  -H "Authorization: Bearer $PINBOARD_OPERATOR_TOKEN"

Response

200

FieldTypeDescription
workersobject[]Sorted by hostname, then sessionId.
workers[].sessionIdstringCurrent session.
workers[].clientIdstringProcess id; target for drain.
workers[].advertiseUrlstringWhere Pinboard forwards.
workers[].namespacesstring[]Registered namespaces, filtered.
workers[].hostnamestringRegistered hostname; * in single-hostname mode.
workers[].envsobject{namespace: env}; values * in single-hostname mode.
workers[].takeover"wind_down" | "deny"Registered takeover.
workers[].headroomnumberLast heartbeat's headroom minus placements made since.
workers[].drainingbooleanOwn drain or operator drain.
workers[].degradedSinceintegerPresent while the challenge probe fails. Unix ms.
workers[].expiryintegerLease end, Unix ms.

secret and account are never returned.

{
  "workers": [
    {
      "sessionId": "3f9c0d6e2b1a4c7d8e9f0a1b2c3d4e5f",
      "clientId": "c1e0b7a94f6d4a1e9b2c3d4e5f60718a",
      "advertiseUrl": "http://10.0.3.17:8000",
      "namespaces": ["/threads"],
      "hostname": "*",
      "envs": { "/threads": "*" },
      "takeover": "wind_down",
      "headroom": 94,
      "draining": false,
      "expiry": 1762560015000
    }
  ]
}

Errors

StatusBodyWhen
401{"error":"unauthorized"}No accepted credential
403{"error":"forbidden"}No pinboard:operator scope, or malformed claim
503{"error":"not the serving fleet"}Node not serving. Retry-After: 1.
404{"error":"not found"}Method other than GET