hosts_list
const url = 'https://api.updawg.net/v1/orgs/example/hosts';const options = {method: 'GET'};
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://api.updawg.net/v1/orgs/example/hostsParameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Organization slug.
Query Parameters
Section titled “Query Parameters”Repeatable. An unknown value matches nothing rather than being refused: host_status is a database enum this build does not mirror, so it must not claim to know every state a host can be in.
Repeatable, key=value. Several labels intersect, because a set of labels is a selector. Split on the first = only.
Repeatable.
Repeatable: yes, no or unknown. Three-valued because the column is — a host that cannot answer is not a host answering no.
hostname (default), last_seen or security_updates.
The hst_… id of the last host on the previous page.
Responses
Section titled “Responses”A page of the fleet.
object
object
How its agent was installed and the channel it follows. A package install updates only to builds its own repository’s channel holds. Absent: an agent too old to say.
object
The channel the package repository follows, e.g. stable. Absent for
a binary install, which can take a build from any channel.
apt or dnf (the package from pkg.updawg.net), binary
(install.sh’s binaries, updated from the signed manifest), or other.
⚠️ A ceiling, not a setting. The host’s own agent.toml decides
this; the server may narrow it and can never widen it. A portal that
renders it as editable is describing a control that does not exist.
Its package sources are pinned in time (DAWG-233): updates is
measured against a snapshot that does not move. ⚠️ Zero updates on a
frozen host is not “patched”, least of all when behind.
object
Known to be behind what it is offered. false also when nobody can
tell.
releasever (dnf’s release is fixed: Amazon Linux 2023, or
/etc/dnf/vars/releasever), snapshot (apt sources on a dated
archive snapshot), or other from an agent newer than this server.
The newest release it is offered, where its agent can tell.
What it is pinned to: 2023.5.20240805, 9.2, 20240101T000000Z.
⚠️ A selector, not decoration. A policy that targets several labels
intersects them, and the fleet filter takes them as repeatable
key=value, so a client that cannot see the type cannot build either.
String to string, enforced by hosts_labels_are_strings rather than
asserted here (DAWG-261).
object
Identity, and not the hostname. Hostnames change and repeat.
⚠️ Three-valued. null is “this host cannot say”, which is not
false. A distribution with no way to answer must not read as “nothing
to do here”.
Whether this host can take snapshots, and so be rolled back
(DAWG-115). ⚠️ null is an agent too old to say, not a host that
cannot: that one has a reason and no provider.
object
The provider in use, e.g. snapper. Absent: none, and reason says
why.
⚠️ null means never evaluated, not zero. A host that has never
uploaded an inventory has never been looked at, and rendering that as
“0 updates” tells somebody their unevaluated fleet is fully patched.
object
Updates that will leave the host needing a reboot — distinct from
reboot_required, which is whether it needs one now.
Examplegenerated
{ "hosts": [ { "agent_install": { "channel": "example", "method": "example" }, "agent_mode": "example", "agent_permissions": [ "example" ], "agent_version": "example", "arch": "example", "display_name": "example", "distro": "example", "distro_version": "example", "enrolled_at": "2026-04-15T12:00:00Z", "frozen": { "behind": true, "kind": "example", "latest": "example", "pinned": "example" }, "hostname": "example", "id": "example", "kernel_version": "example", "labels": { "additionalProperty": "example" }, "last_inventory_at": "2026-04-15T12:00:00Z", "last_seen_at": "2026-04-15T12:00:00Z", "machine_id": "example", "os_family": "example", "reboot_required": true, "services_need_restart": [ "example" ], "snapshots": { "provider": "example", "reason": "example" }, "status": "example", "updates": { "requiring_reboot": 1, "security": 1, "total": 1 } } ], "next": "example", "total": 1}A filter, sort or cursor that cannot be honoured. Refused rather than ignored: a page that looks filtered and is not is the failure worth preventing.
object
Examplegenerated
{ "detail": "example", "status": 1, "title": "example", "type": "example"}No session.
object
Examplegenerated
{ "detail": "example", "status": 1, "title": "example", "type": "example"}Not permitted.
object
Examplegenerated
{ "detail": "example", "status": 1, "title": "example", "type": "example"}No such organization, or not yours.
object
Examplegenerated
{ "detail": "example", "status": 1, "title": "example", "type": "example"}Over the organization’s request limit. Retry-After says when to try again; RateLimit-Limit is the burst.
object
Examplegenerated
{ "detail": "example", "status": 1, "title": "example", "type": "example"}