# Monitoring locations reference

HostTracker checks your targets from monitoring locations (checkpoints) around the world. You choose where a monitor
runs by picking **pools** - named groups of locations - rather than individual machines. This page is the reference;
to set your account's defaults and a monitor's locations in the app, see
[Set your default locations](/monitors/default-locations/).

## Locations and pools

- A **location** (also called an agent or checkpoint) is one vantage point, with a country, region and city.
- A **pool** is a named group of locations - a region, a sub-region, or `allworld` (everywhere). Pools nest: a pool
  can list child pools and parent pools.
- A monitor runs from the locations of the pools you pick, minus any locations you exclude.
- Pools have separate location sets for ordinary checks and for browser checks (page speed, transaction, content
  check); `GET /agent/pool` shows both counts per pool.

The pool list is data kept on HostTracker's side, not a fixed list in the API, so `GET /agent/pool` (MCP
`list_locations`) is always the authority. The regional pool ids below have been in use for years and are the ones most
requests need.

## Common pool ids

| Pool id | Covers |
|---|---|
| `allworld` | Every public location |
| `westeurope` | Western Europe |
| `easteurope` | Eastern Europe |
| `northamerica` | North America |
| `southamerica` | South America |
| `asia` | Asia |
| `australia` | Australia |
| `africa` | Africa |

- **There is no single `europe` pool.** For "Europe", send both: `["westeurope", "easteurope"]`.
- **The app's default** for a new monitor, when your account has no default locations of its own, is
  `westeurope` + `easteurope` + `northamerica`. The API and MCP apply no default: send the pools yourself.
- **Other pools.** `GET /agent/pool` also lists smaller regional pools, and a signed-in call adds pools private to
  your account. Use the ids exactly as listed there.
- **Ids are matched case-insensitively** (`NorthAmerica` is `northamerica`); write them in lower case as listed.

To check an id before using it, or to see how many locations each pool has for ordinary and browser checks:

```bash
curl https://api2.host-tracker.com/agent/pool
```

Each row carries `id`, `name`, `agents` (location count per fleet: `net` for ordinary checks, `waterfall` for
browser checks), `children`, `parents`, `hidden` and `priority`; `summary` carries `minAgents` (the minimum number
of locations per monitor type), `minIntervals`, and - with a token - your account's `defaults` and saved `presets`.

## Which monitor types use locations

| Types | Where they run | Locations setting |
|---|---|---|
| Website/HTTP, API, Ping, Port | Public monitoring locations | yes - pools, fallback, excluded locations |
| Page speed, Transaction, Content check | Browser-capable locations | yes |
| SSL expiry | Public monitoring locations HostTracker picks, on a fixed schedule | no - a `locations` value is refused |
| Domain expiry, DNSBL, Web Risk | HostTracker's internal network, on a fixed schedule | no - a `locations` value is refused |
| Database, SNMP, Counter | HostTracker's private network | no |

## Monitor location settings

| Setting | API field | Allowed values | Default | What it does |
|---|---|---|---|---|
| Pools | `locations.pools` | One or more pool ids; `["allworld"]` for everywhere | required when creating a location-based monitor through the API; the app's form pre-fills your account defaults | Where the monitor runs. |
| Fallback | `locations.fallback` | `geo`, `world`, `starve`, or `null` for the service default | service default (`starve`) | What happens when none of the chosen pools' locations is available. |
| Excluded locations | `locations.excludedAgents` | Location ids | none | Keeps the monitor off specific locations. |

Fallback modes:

| Mode | Behaviour |
|---|---|
| `geo` | Use the nearest available locations, then any location in the world. |
| `world` | Use any available location in the world. |
| `starve` | Do not substitute; wait until a chosen location is free and try again. This is the default. |

A monitor needs a minimum number of matching locations for down detection to work. A selection with too few answers
`422 insufficient_agents` (with `required`, `matched` and a per-pool breakdown); an unknown pool id answers
`422 unknown_pool` with the valid ones.

## How a monitor's locations are decided

1. **When the monitor is created**, it gets its own pool list. In the app, the create form starts from your
   account's default locations (Profile -> Defaults; `defaultAgentPools` via `PATCH /account`), which you can
   change before saving. Through the API or MCP there is no such seed: a create for a location-based type
   (HTTP, API, Ping, Port, Page speed, Transaction, Content check) must send `locations.pools`, or it is refused
   with a `422` naming the missing member. Changing your account defaults later does not change existing monitors.
2. **At check time**, the monitor runs from its pools, minus excluded locations. A monitor with an empty pool list
   (possible on older monitors) runs from all locations, like `allworld`.
3. If none of the chosen locations is available, the **fallback** mode decides - `starve` by default.

## List pools, locations and addresses

These endpoints need no token (sending one adds your saved presets and hidden pools):

| Endpoint | Returns |
|---|---|
| `GET https://api2.host-tracker.com/agent/pool` | Every pool: `id`, `name`, location counts per fleet, `children`, `parents`; plus `summary.minAgents`, `summary.minIntervals` and, with a token, your `defaults` and presets. |
| `GET https://api2.host-tracker.com/agent` | Every location with its country, region and city. |
| `GET https://api2.host-tracker.com/agent/ip` | The IP addresses checks originate from - for firewall and WAF allow-lists. |

MCP: `list_locations` (pools; with `agents=true`, individual locations). Terraform: the `hosttracker_locations` data
source. Instant checks accept the same pool ids.

`GET /agent/ip` is limited to 60 anonymous requests per 5 minutes per address; fetch it on a schedule rather than on
every request.

## Related

- [Set your default locations](/monitors/default-locations/)
- [How down detection works](/monitors/down-detection/)
- [Why is it down](/incidents/why-is-it-down/)
- [Monitor settings reference](/reference/monitor-settings/)