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). The pool ids most requests need - allworld, westeurope, easteurope, northamerica, southamerica, asia, australia, africa - are listed in 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). 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 [email protected].

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.

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 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):

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):

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):

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).

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
• Recheck strategy
• Monitoring locations reference
• Bulk operations