---
title: WatchFor hosts API — servers running watchfor-agent
description: List your servers, read their liveness and current CPU, memory and disk gauges, and pull metric time series — the same data the Hosts pages show.
canonical: https://watchfor.io/docs/api/hosts
---

# WatchFor hosts API — servers running watchfor-agent

List your servers, read their liveness and current CPU, memory and disk gauges, and pull metric time series — the same data the Hosts pages show.

A **host** is a server running [watchfor-agent](/docs/hosts). The API is
read-only: hosts are added from the dashboard (that is where the agent's
token is issued) and removed there. Everything the Hosts page shows is
here — liveness, the latest gauges and the metric history.

| Method | Path | Scope | operationId |
| --- | --- | --- | --- |
| GET | `/v1/hosts` | read | `listHosts` |
| GET | `/v1/hosts/{id}` | read | `getHost` |
| GET | `/v1/hosts/{id}/metrics` | read | `getHostMetrics` |

The host object:

```json
{
  "id": "7c1e…",
  "object": "host",
  "name": "db-01",
  "host_id": "f0a3…",
  "description": null,
  "status": "online",
  "last_seen_at": "2026-09-22T14:02:11.000Z",
  "agent_version": "0.8.0",
  "os": "Ubuntu 24.04.3 LTS",
  "kernel": "6.8.0-79-generic",
  "arch": "arm64",
  "tags": ["role=db", "env=prod"],
  "push_interval_seconds": 15,
  "monitor_id": "0b0f6a41-…",
  "hardware": "Amazon EC2 t4g.small",
  "cpu_model": "Neoverse-N1",
  "cpu_cores": 2,
  "memory_bytes": 2013265920,
  "virtualization": "kvm",
  "addresses": {
    "primary": "172.31.4.20",
    "primary_v6": null,
    "public": ["16.171.2.40"],
    "reporting_from": "16.171.2.40"
  },
  "metrics": { "cpu_pct": 7.4, "memory_pct": 61.2, "disk_pct": 48.9, "sampled_at": "2026-09-22T14:02:11.000Z" },
  "created_at": "2026-09-14T09:30:00.000Z"
}
```

- `status` — the agent's liveness: `online` (batches arriving), `stale`
  (three push intervals missed, never sooner than 90 s), `offline` (none for
  10 minutes), `never` (the agent has not reported yet). Same thresholds as
  the dashboard.
- `monitor_id` — the host's internal monitor. Its alert rules, incidents and
  uptime hang on it, so pass this id wherever a monitor id is expected:
  [status-page components](/docs/api/status-pages), maintenance windows,
  `GET /v1/incidents?monitor_id=`, `GET /v1/monitors/{id}/uptime`.
- `metrics` — the latest CPU, memory and fullest-mount disk usage from the
  last five minutes, `null` when the host is silent.
- A revoked host is not listed. The agent token never appears in the API.

## List hosts

`GET /v1/hosts?status=offline` narrows to one liveness state. Newest first,
cursor-paginated like every list.

```bash
curl https://watchfor.io/api/v1/hosts?status=offline \
  -H "Authorization: Bearer wf_live_YOUR_KEY"
```

## Metric time series

`GET /v1/hosts/{id}/metrics?metrics=cpu.usage_pct,mem.used_pct,disk.used_pct&range=24h`

| Parameter | Required | Notes |
| --- | --- | --- |
| `metrics` | yes | Comma-separated, 1–28 names from the agent's catalogue |
| `range` | no | `1h`, `6h`, `24h` (default), `7d`, `30d` |

Points are `[unix seconds, value]`, bucketed to the range's step exactly
like the host page's charts (raw samples for short ranges, minute and hour
rollups beyond). A metric with labels — `disk.used_pct` per mount,
`net.rx_bytes_per_s` per interface — comes back as one series per label
set:

```json
{
  "object": "host_metrics",
  "host_id": "7c1e…",
  "range": "24h",
  "step_seconds": 300,
  "from": "2026-09-21T14:05:00.000Z",
  "to": "2026-09-22T14:05:00.000Z",
  "series": [
    { "metric": "cpu.usage_pct", "labels": {}, "points": [[1790000100, 6.1], [1790000400, 7.4]] },
    { "metric": "disk.used_pct", "labels": { "mount": "/" }, "points": [[1790000100, 48.9]] }
  ]
}
```

Metric names: `cpu.usage_pct`, `cpu.user_pct`, `cpu.system_pct`,
`cpu.iowait_pct`, `cpu.steal_pct`, `load.1`, `load.5`, `load.15`,
`mem.used_pct`, `mem.used_bytes`, `mem.total_bytes`, `mem.cached_bytes`,
`swap.used_bytes`, `disk.used_pct`, `disk.used_bytes`, `disk.free_bytes`,
`disk.inodes_used_pct`, `diskio.read_bytes_per_s`, `diskio.write_bytes_per_s`,
`net.rx_bytes_per_s`, `net.tx_bytes_per_s`, `net.rx_packets_per_s`,
`net.tx_packets_per_s`, `net.tcp_in_use`, `net.tcp_time_wait`, `proc.total`,
`proc.running`, `proc.blocked`, `proc.zombie`, `sys.uptime_s`,
`sys.context_switches_per_s`. See [what is collected](/docs/hosts#what-is-collected).

## For agents

The same data is available as the MCP tools `list_hosts`, `get_host` and
`get_host_metrics`, and as the A2A skill `check-hosts`.

---

Canonical page: https://watchfor.io/docs/api/hosts · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt