Skip to content
HostTracker Docs

Monitoring locations reference

View as Markdown

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.

Locations and pools

Section titled “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

Section titled “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:

Terminal window
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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Section titled “Related”