The registered poller fleet plus the per-pool summary.

GET

/api/v1/pollers

const url = 'https://example.com/api/v1/pollers';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/api/v1/pollers \
  --header 'Authorization: Bearer <token>'

Authorizations

bearer

Responses

200

Every known poller (live ∪ durable inventory) and the per-pool summary

application/json

The GET /api/v1/pollers body: the fleet of pollers + the per-pool summary.

object

pollers

required

Array<object>

One poller in the GET /api/v1/pollers response — a merge of the live registry (current status/telemetry) and the durable inventory (so an offline poller still lists). No secrets.

object

anchor_node_id

The node this poller attaches to, naming where it sits in the derived dependency graph. null ⇒ core places it from mgmt_addrs instead.

string | null format: uuid

can_change_pool

required

Whether this poller can be moved to another pool from the WebUI (ADR-107 Inc.2).

true when the build advertises pool-follow: it reads its pool off the working set, re-points the three pool-derived subjects and reconnects the bus, so a move takes effect without anyone touching the site.

⚠️ false for every poller that is offline, and for every build older than this one. Derived here rather than left to the client to look for in caps, so the token itself is written down once — and because “cannot” and “cannot be asked right now” are the same answer to the only question the UI has, which is whether to offer the control.

boolean

caps

required

Optional capabilities this poller’s build advertises (raw-capture, flow-relay, http-auth, http-body, self-upgrade). Empty when the poller is offline, and empty from an N-1 build — absence means “cannot”, never “unknown”, which is the same reading core applies when it decides whether to send a poller work that depends on one.

Array<string>

cpu_pct

Current host CPU utilization % (0–100) from its latest heartbeat; null when the poller is offline or on an N-1 build without host telemetry.

number | null format: double

disk_used_pct

Highest watched-filesystem used % (0–100); null when unavailable.

number | null format: double

first_seen

First durably-recorded contact (RFC 3339); null if not yet persisted.

string | null

has_token

required

Whether this poller has a bus token of its own (ADR-065). false means it is admitted by the deployment-wide bootstrap secret, which every poller was before tokens existed and which a co-located poller on an unencrypted internal bus still is.

boolean

required

Sanitized poller id (stable across restarts).

string

last_seen

Last durably-recorded contact (RFC 3339); null for a live poller not yet persisted (it registers within the 60s inventory-upsert throttle window).

string | null

listeners

required

Passive-event listeners it has bound (e.g. syslog:514, trap:162). Empty when offline.

Worth reading before restarting a poller: unlike active polling, nothing can take these over and nothing backfills them, so whatever they would have received while it was down is gone (the same set monitoring_gaps stamps onto a healed gap).

Array<string>

mem_used_pct

Current host memory-used % (0–100); null when unavailable.

number | null format: double

mgmt_addrs

required

Interface addresses the poller reported for itself. Empty for an older poller build, and empty for a containerized poller whose only address is a container-network one.

Array<string>

pool

required

Pool it serves (live view wins; else the durable row).

string

results_total

required

Poll results core has consumed from it since core started.

integer format: int64

status

required

"online" when it is beating within the offline window, else "offline".

string

token_issued_at

When its token was issued, RFC 3339. null when it has none.

string | null

upgrade

One of:

null
object

null

What its site updater last reported about an upgrade (ADR-051 Inc.4); null when it has no updater, has never been asked, or predates the field.

This is the visible half of decision 18: a WAN pull is minutes, so without it the operator who pressed “bring them to this build” watches an unchanged screen and cannot tell a site that is working from one that is stuck.

object

command

required

Which half of the upgrade the site is in.

string

Allowed values: prefetch apply other

message

required

A sentence for the operator, written at the site.

string

state

required

How it is going.

string

Allowed values: running succeeded failed unknown

step

required

Where in the command it is: pull, compose, verify, start. Free text on purpose — it is shown as a detail, never keyed on, so a site updater may add a step without this core needing a name for it.

string

version

Build version from its latest heartbeat (or the durable row when it is offline).

string | null

working_set_nodes

required

Working-set node count it last reported (0 when offline / never reported).

integer format: int32

working_set_specs

required

Working-set spec count it last reported.

integer format: int32

pools

required

Array<object>

One pool in the GET /api/v1/pollers response — node count vs. live pollers, its dispatch mode, and a warning when it has nodes but no live poller (they would go unmonitored).

object

covered_by

The pool currently polling this one’s members on its behalf (ADR-107 Inc.4), if an operator asked for that. null is the ordinary case.

⚠️ A covered pool will usually also read nodes: 0 with no warning — its members are somewhere else, which is the point. The two fields answer different questions: warning is “is anything here unmonitored”, this is “is somebody standing in for it”.

string | null

description

Why this pool exists, in the operator’s words (ADR-107). null for a pool nobody has described — which is every pool that predates the pools table.

string | null

live_pollers

required

Live (online) pollers serving this pool.

integer

mode

required

"working_set" when a live poller serves it, else "legacy" (per-job fallback).

string

nodes

required

Non-Meraki nodes assigned to this pool.

integer

pool

required

Pool name (default for unassigned nodes).

string

warning

"nodes_without_live_poller" when the pool has nodes but no live poller, else null.

string | null

Example

{
  "pollers": [
    {
      "upgrade": {
        "command": "prefetch",
        "state": "running"
      }
    }
  ]
}

401

No valid bearer token

application/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks the View permission

application/json

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Skeleton mode: no poller inventory

application/json

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

The registered poller fleet plus the per-pool summary.

Authorizations

Responses

200

Example

401

Examplegenerated

403

Examplegenerated

503

Examplegenerated

Example^generated

Example^generated

Example^generated