# Choose monitoring locations

HostTracker checks your sites from a worldwide network of checkpoints. The **locations** of a monitor decide
where each check runs from, which checkpoints confirm a failure, and whose network path your response-time
graphs describe. Set a sensible **account default** once so every new monitor starts in the right place, and
**override it per monitor** when a site has a regional audience.

## How locations are organised

- A **checkpoint** (API: *agent*) is one monitoring machine in one city, with its own IP address.
- A **pool** is a named group of checkpoints: **All world** (`allworld`), regions such as West Europe
  (`westeurope`), East Europe (`easteurope`) or North America (`northamerica`), and nested groups down to
  countries. Pools can contain other pools.
- In the location picker you tick a whole pool, part of it, or single checkpoints. Unticking one checkpoint inside
  a ticked pool stores an **exclusion** (`-<checkpoint id>`), so "North America except these two cities" is one
  selection.
- Each check family has its own fleet, so the picker shows different checkpoints per type: web, API, ping, port
  and crawl checks use the main fleet; **Page speed**, **Transaction** and **Web content check** use the browser
  fleet. SSL and domain expiry, DNSBL, Web Risk, Database, SNMP and Counter checks have no location picker:
  HostTracker places them itself (SSL certificate checks on the main fleet, the others on its internal network).

For the live list of pools and checkpoints, see the picker itself or `GET /agent/pool` and `GET /agent`
([Monitoring locations reference](/reference/locations/)). The pool ids most requests need - `allworld`,
`westeurope`, `easteurope`, `northamerica`, `southamerica`, `asia`, `australia`, `africa` - are listed in
[Common pool ids](/reference/locations/#common-pool-ids). There is no single `europe` pool: use `westeurope` and
`easteurope` together.

## Settings reference

| Setting (app label) | API field (v2) | Type / allowed values | Default | Plan limits | What it does for you |
|---|---|---|---|---|---|
| **Monitoring Locations** (the location tree) | `locations.pools` | Array of pool ids, checkpoint ids and `-<checkpoint id>` exclusions; at least 1 entry | In the app: your profile default (below). On the API: required on create for location-based types | None | Where the check runs from. Each scheduled check runs from one of these checkpoints, taken in turn. |
| (unticking single checkpoints) | `locations.excludedAgents` | Array of checkpoint ids | Empty | None | Keeps specific checkpoints off this monitor. |
| **If selected locations are unavailable** | `locations.fallback` | `starve` (**Selected locations only**), `geo` (**Closest locations**), `world` (**Any location**); `null` clears | Selected locations only | None | What happens when none of your chosen checkpoints is available. |
| Minimum number of locations | - (account setting, not editable in the app) | Integer | 7 for every location-based type; 1 for a site crawl | None | A selection that resolves to fewer checkpoints is refused, so a failure can always be confirmed by several witnesses. |
| **Default monitoring locations** (Profile -> Defaults) | `defaultAgentPools.net`, `defaultAgentPools.waterfall` (on `/account`) | Same values as `locations.pools`, up to 100 per family | West Europe + East Europe + North America (All world if those pools are unavailable) | None | The selection a new monitor starts with in the app. |

## Why at least 7 locations

A failure is confirmed by re-checking from several other checkpoints (see
[How down detection works](/monitors/down-detection/)). To make that possible, a monitor's selection must resolve
to at least **7 checkpoints** of its fleet. The picker shows **"Please select at least 7 locations"** while you are
below the minimum, and the API refuses the write with `422 insufficient_agents`, naming the required and matched
counts per pool. A site crawl is the exception: it runs from exactly **one** location. If you have a genuine need
for fewer locations, contact support at `ht2support@host-tracker.com`.

## Set the account default

The default is what the **Add Monitor** form pre-selects. It does not change existing monitors unless you ask.

1. Open **Profile** in the left sidebar and switch to the **Defaults** tab.
2. Scroll to **Default monitoring locations**.
3. In the dropdown choose which family you are editing: **Locations for monitorings Web, Ping, Port** (also
   used by API checks) or **Locations for monitoring PageSpeed** (also used by Transaction and Web content checks).
4. Tick pools or single checkpoints in the tree. Use **Search locations...** to find a city or country, and the
   **A-Z** / **Points** buttons to sort by name or by number of checkpoints.
5. Optional: tick **Apply locations to existing monitoring tasks** to overwrite the locations of every existing
   monitor of that family with this selection.
6. Click **Save** at the bottom of the page.

:::caution[Apply to existing overwrites]
**Apply locations to existing monitoring tasks** replaces each existing monitor's own selection; there is no
undo. Check a few monitors afterwards. To re-point only some monitors, use
[bulk edit](/monitors/bulk-operations/) instead: select them on **Sites** -> **Edit** -> **Monitoring Locations**.
:::

## Override the locations of one monitor

1. On **Sites**, open the monitor (click its row, or the row menu -> **Edit**).
2. Expand **Monitoring Locations**.
3. Tick or untick pools and checkpoints. Shortcuts above the tree:
   - **Copy locations from another task...** - reuse a selection one of your other monitors already has.
   - **Use profile locations** - reset to your account default.
   - **Save as profile default** - make this selection your new default.
4. If you picked specific regions (not All world), choose **If selected locations are unavailable**.
5. **Save**.

## Choose the fallback

A checkpoint can be temporarily unavailable (busy, restarting, or distrusted after bad results). The fallback
decides what a monitor does when **none** of its chosen checkpoints can run a check:

| App option | API value | Behaviour | Use when |
|---|---|---|---|
| **Selected locations only (default)** | `starve` | Wait and retry until one of your checkpoints is free again. No data from elsewhere, no false alerts from an unexpected region. | You need the check to run only where you chose (the default). |
| **Closest locations** | `geo` | Run from the nearest available checkpoints instead. | Location matters, but a skipped check matters more. |
| **Any location** | `world` | Run from any available checkpoint worldwide. | Coverage matters most, location least. |

The fallback selector appears only when you have chosen specific regions; with All world there is always a
checkpoint available.

## Do it with the API or MCP

List the pools and the per-type minimum (no token needed; a token adds your own defaults and presets):

```bash
curl https://api2.host-tracker.com/agent/pool
# summary.minAgents   -> the minimum per monitor type
# summary.defaults    -> your default selection per family (with a token)
# summary.presets     -> selections your monitors already use
curl "https://api2.host-tracker.com/agent?country=DE" -H "Authorization: Bearer $HT_TOKEN"   # single checkpoints
```

Pin one monitor to Europe, falling back to the closest checkpoints (scope `monitor:write`):

```bash
curl -X PATCH "https://api2.host-tracker.com/monitor/$MONITOR_ID" \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "locations": { "pools": ["westeurope", "easteurope"], "fallback": "geo" } }'
```

Set the account defaults (scope `account:write`). The map **replaces** the stored one, so send both families;
`null` clears every default and an empty array clears one family. `net` is the web/ping/port/API family,
`waterfall` the browser family (a read may also show a `legacy` key - the older spelling of `net` written by the
app):

```bash
curl -X PATCH https://api2.host-tracker.com/account \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "defaultAgentPools": { "net": ["allworld"], "waterfall": ["westeurope", "northamerica"] } }'
```

Re-point many existing monitors: `POST /monitor/bulk-update` with `{ "ids": [...], "patch": { "locations": { "pools": [...] } } }`
(see [Bulk operations](/monitors/bulk-operations/)).

MCP tools: **`list_locations`** (pools; `agents=true` for single checkpoints, filtered by `country` or `pool`),
**`create_monitor`** / **`update_monitor`** (`pools` argument, comma-separated), **`bulk_update_monitors`**
(`patchJson` with `locations`). `update_monitor` sets pools only - use **`api_request`**
(`PATCH /monitor/{id}`) for `fallback` and `excludedAgents`, and for `PATCH /account`.

## What happens next

The new selection applies from the next scheduled check, within about a minute of saving. Past results keep the
location they were taken from.

## Limits and gotchas

- The account default is applied by the app's **Add Monitor** form only. A monitor created through the API or MCP
  gets exactly the `locations.pools` in the request.
- `locations.pools: []` and blank entries are refused (`422 validation_failed`, `reason: "empty"`). To check from
  everywhere send `["allworld"]`; to leave the selection unchanged, omit `locations`.
- An unknown pool id answers `422 unknown_pool` with the list of valid pools.
- Types without a location picker refuse any selection (`422 validation_failed`,
  `reason: "pool_not_supported_for_type"`) - omit `locations` for them.
- Some pools overlap (a checkpoint can belong to two regions). The picker shows each checkpoint once.

## Related

- [How down detection works](/monitors/down-detection/)
- [Recheck strategy](/monitors/advanced/recheck-strategy/)
- [Monitoring locations reference](/reference/locations/)
- [Bulk operations](/monitors/bulk-operations/)