Skip to content
Yagra

The registered poller fleet plus the per-pool summary.

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

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

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

Media typeapplication/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
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
id
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
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
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
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
Examplegenerated
{
  "pollers": [
    {
      "anchor_node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "cpu_pct": 1,
      "disk_used_pct": 1,
      "first_seen": "example",
      "id": "example",
      "last_seen": "example",
      "mem_used_pct": 1,
      "mgmt_addrs": [
        "example"
      ],
      "pool": "example",
      "results_total": 1,
      "status": "example",
      "version": "example",
      "working_set_nodes": 1,
      "working_set_specs": 1
    }
  ],
  "pools": [
    {
      "live_pollers": 1,
      "mode": "example",
      "nodes": 1,
      "pool": "example",
      "warning": "example"
    }
  ]
}

401

Section titled “401”

No valid bearer token

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

Role lacks the View permission

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Section titled “503”

Skeleton mode: no poller inventory

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}