banshee/storage-collection/storage/truenas/https/api-v2.0/
snapshots
The state of each periodic snapshot task of a TrueNAS, to see a task in error, by its REST API v2.0.
by banshee1 installation1 version
Published on October 27, 2026. First version.
Snapshot tasks of a TrueNAS, by its REST API
Returns the state of each periodic snapshot task of a TrueNAS, so that a snapshot task in error is seen, read from the REST API behind an API key. Three 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, and was removed in TrueNAS 26. Hence the folder api-v2.0.
How it works
One GET https://<host:address>/api/v2.0/pool/snapshottask, the key in the header Authorization: Bearer. The API answers a list of tasks:
[{"id": 3, "dataset": "tank/home", "naming_schema": "auto-%Y-%m-%d_%H-%M", "enabled": true, "state": {"state": "FINISHED", …}, …}]- A task is named after its dataset; two tasks on one dataset (hourly and daily) each keep their own, the second carrying its id (
tank/home #7). - The state is the one TrueNAS's replication engine (zettarepl) gives the task, in lower case:
running,finished,error,hold(its definition stops it); a task with no state yet (never run) readspending. - A task disabled in TrueNAS reads
disabled, and raises nothing. - No task returns no value, and raises nothing.
The key comes from protocol:http:token, a secret variable: it only goes in the header. The answer is not secret.
Prerequisites
- The web interface of TrueNAS reachable from the poller in HTTPS, on port 443 of the host's address, its certificate trusted by the TLS profile of the probe (a pinned fingerprint in
protocol:http:fingerprint, or the certificate underprotocol:tls:authorities). - An API key in
protocol:http:token, of a user of the read-only administrator role where SCALE has roles.
Outputs
| Name | Label | Unit | Per instance |
|---|---|---|---|
state | State | — | yes, per snapshot task |
Watches
| Name | Title | Kind | Defaults | Checked by default |
|---|---|---|---|---|
failed | Snapshot task in error | state to avoid, on state | critical on error | yes |
held | Snapshot task on hold | state to avoid, on state | warning on hold | yes |
missing | Snapshot task missing | expected instances, on state | no task named: it raises nothing until names are set on the probe | no |
Limits
- The reason of an error is not returned: it is read in TrueNAS, on the task.
- The age of the last snapshot is not judged: a task whose schedule no longer fires keeps its last state.
- The second task on a dataset is named by its order in the list: if the first one is removed, the second takes the dataset's name.
- Not checked against a TrueNAS: the fields are those of
pool.snapshottask.queryin the API documentation of TrueNAS 25.10, which does not detailstate; its states are those the TrueNAS middleware writes (plugins/zettarepl.py, branchstable/fangtooth).