# List nodes

`GET https://api.mailmasker.org/api/v1/admin/agent/hosts`

Every node whose agent has ever checked in, and when it last did.

- Who can use it: Site admins
- Area: Fleet and status
- Answers 200 OK when it works
- Page: https://developer.mailmasker.org/admin-list-nodes

In name order: each node's address, the port its agent listens on, the agent's version, and when it last checked in. Agents check in about once a minute, so a `last_heartbeat` more than a few minutes old means that node has gone quiet.

## Good to know

- A node that has been switched off stays on the list; only its `last_heartbeat` stops moving.
- A node missing from the list has never finished enrolling.

## Examples

cURL:

```bash
curl -s 'https://api.mailmasker.org/api/v1/admin/agent/hosts' \
  -H "Authorization: Bearer $TOKEN"
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->get('https://api.mailmasker.org/api/v1/admin/agent/hosts',
    { Authorization => "Bearer $ENV{TOKEN}" })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli admin fleet status
```

## Response

200 OK:

```json
[
  {
    "hostname": "prod-homelab12",
    "address": "192.0.2.12",
    "agent_port": 2520,
    "agent_version": "0.1.9",
    "last_heartbeat": "2026-11-03 21:42:10.123456-06"
  },
  {
    "hostname": "prod-homelab13",
    "address": "192.0.2.13",
    "agent_port": 2520,
    "agent_version": "0.1.9",
    "last_heartbeat": "2026-11-03 21:41:47.880315-06"
  }
]
```