Community

banshee is under active development: collectors will keep changing, and a version you publish will likely need adjustments. For stable use, wait for version 1.0.0.

Storage

banshee/storage-collection/storage/truenas/https/api-v2.0/

pools

The health and the space of each ZFS pool of a TrueNAS by its REST API v2.0.

  • storage
  • truenas
  • zfs
  • pool
  • https
  • api

by banshee1 installation2 versions

v2Latest

Published on October 28, 2026. One naming convention across collections; documentation completed.

Pools of a TrueNAS, by its REST API

Returns, for each ZFS pool of a TrueNAS, its health, its used space, its free space and its size, read from its REST API behind an API key. Five watches are offered, each one set on the probe.

Versions

Written for the REST API v2.0, which answers on TrueNAS CORE 12 and 13 and on TrueNAS SCALE up to 25.10. TrueNAS deprecated it in 25.04 and removed it in 26, for a JSON-RPC API over WebSocket that Keen does not speak. Hence the folder api-v2.0.

How it works

One GET https://<host:address>/api/v2.0/pool, the key in the header Authorization: Bearer. The API answers a list of pools:

[{"name": "tank", "status": "ONLINE", "healthy": true, "size": 3985729650688, "allocated": 1052266987520, "free": 2933462663168, ...}]
  • The health is status, in lower case: online, degraded, faulted, offline, unavail, removed, suspended.
  • The used space is allocated over size, as zpool list shows its capacity; sizes are in bytes, returned in GiB.
  • Only an online or degraded pool's space is read: an exported or failed pool may have none.
  • A code 401 or 403 stops the collector misconfigured (the key is refused); any other code but 200 stops it unreachable.

The key comes from protocol:http:token, a secret variable: it only goes in the header, never in a value returned. The answer is not secret, its body having carried none.

Prerequisites

  • The web interface of TrueNAS reachable from the poller in HTTPS, on port 443 of the host's address. Its certificate follows the TLS profile of the probe: the self-signed certificate TrueNAS makes at install is trusted by pinning its fingerprint (protocol:http:fingerprint) or by adding it under protocol:tls:authorities.
  • An API key in protocol:http:token. On a recent SCALE, a key belongs to a user: make it for a user of the read-only administrator role.

Outputs

NameLabelUnitPer instance
healthHealth—yes, per pool
used-percentUsed space%yes, per pool
freeFree spaceGiByes, per pool
sizeSizeGiByes, per pool

Watches

NameTitleKindDefaultsChecked by default
unhealthyPool not onlineexpected value, on healthwarning when the health is anything but onlineyes
failedPool failedstate to avoid, on healthcritical on faulted, unavail, removed, suspendedyes
usedUsed spaceabove a threshold, on used-percentwarning above 80 %, critical above 90 %yes
full-soonFull within a weekabove a threshold, on used-percentwarning above 99 %, ahead 7 dyes
missingPool missingexpected instances, on healthno pool named: it raises nothing until names are set on the probeno

Limits

  • From TrueNAS 25.10.1, each call to the REST API raises a TrueNAS alert that a deprecated endpoint is used; storage/truenas/https/api-v2.0/alerts sees it too.
  • The address is written into the URL as is: an IPv6 address must be given as a name.
  • What a JSON null reads as in Keen is not settled yet: a pool whose size is null while online or degraded would stop the collector.
  • Not checked against a TrueNAS: the fields are those of pool.query in the API documentation of TrueNAS 25.10, which the REST GET /pool returns.