What a monitor is

A monitor is one scheduled check of one target. It has a type (what kind of check), an address (URL, host, host:port…), a schedule (an interval or a cron expression), the locations it runs from, a recheck strategy that confirms failures, type-specific settings, and the contacts it alerts. Every check produces a result; a confirmed change between up and down opens or closes an incident.

This page is the reference for the monitor object itself. Each setting has its own page with the details.

The parts of a monitor

Setting (app label)	API field (v2)	Type / allowed values	Default	Plan limits	What it does for you
Monitor type (picked when you click Add Monitor)	type	One of http, api, ping, port, waterfall, tran, cntCheck, database, counter, snmp, dnsbl, domainExp, sslExp, webRisk (and crawl where your plan includes it)	- (required)	Some types are a plan feature	Decides what is checked and which settings exist. It cannot be changed later. See Monitor types.
URL, domain, or IP	url	Text; format depends on the type	- (required for most types; Database and SNMP monitors build it from their settings, and a Counter monitor may send settings.probeUrl instead)	-	The target. HostTracker may normalise it (for example add a trailing /); the read then also shows effectiveUrl, the exact address checked.
Monitor name	name	Text, up to 255 characters	Empty (the address is shown instead)	-	The label used in alerts, reports, widgets and status pages.
Monitoring enabled	enabled	true / false	true	Enabled monitors count toward your plan’s monitor limit	Off = paused: no checks, no alerts. See Pause, enable and delete.
Interval schedule / Cron schedule	interval (seconds) or cronSchedule	See Check intervals	3 minutes for most types	Plan minimum interval; cron is a paid feature	How often the check runs.
Timeout	settings.timeout (milliseconds)	Per type	40 seconds for web types	-	How long one check waits before it counts as failed. See Timeouts and response size.
Tags	tags (addTags / removeTags on update)	Array of strings	None	-	Grouping and filtering. See Tags.
Full Log	fullLog	true / false	false	Plan feature	Keeps every check result instead of grouped events.
Open Stats	openStat	true / false	false	-	Publishes an anonymous public statistics page for the monitor.
Monitoring Locations	locations.pools, locations.fallback, locations.excludedAgents	Pool ids, agent ids	In the app: your profile default. On the API: required on create for the types that run from locations (http, api, ping, port, waterfall, tran, cntCheck, crawl); the other types take none	-	Where the check runs from. See Monitoring locations.
Recheck strategy	recheck.strategy, recheck.minNumDown	See Recheck strategy	Majority vote	-	How a failure is confirmed before the monitor turns Down.
Type-specific settings (Request Configuration, Response Validation…)	settings.*	Per type	Per type	Keywords, assertion count, TLS policy and custom DNS can be plan features	Method, headers, keywords, assertions, TLS policy and so on. See the page for each monitor type.
Attached monitors	attached.dnsbl, attached.sslExp, attached.domainExp, attached.webRisk	Booleans (or objects)	Off	Each sub-check is a plan feature	Extra sub-checks that ride on a web monitor. See Attached sub-checks.
- (API only)	slaTarget	Number 0-100, or null	null	-	Your SLA target percent, used by uptime summaries and reports.
Alert Subscriptions / Report Subscriptions	alertSubscriptions, reportSubscriptions (create only)	Contact ids + event or frequency lists	In the app: all contacts get Up/Down alerts and reports (configurable under Profile -> Defaults)	Contact types and report frequencies depend on your plan	Who hears about this monitor. See Subscribe contacts to monitors.

Read-only members every monitor carries: id, state, since (when the current state began), created, updated, and for certificate and domain expiry monitors expirationDate (plus certNotBefore for certificates). All timestamps are Unix seconds.

The four states

state	Shown as	Meaning
up	green	The last confirmed result was a success.
down	red	A failure was confirmed by the recheck. An incident is open.
maintenance	maintenance marker	The monitor is inside a maintenance window. Checks still run, but it is not reported as down.
paused	grey / Disabled	Not being checked. Either you switched it off (enabled: false) or it is over your plan’s monitor limit.

The state is derived with a fixed precedence: paused, then maintenance, then up/down. A monitor over your plan limit keeps enabled: true but reads state: "paused", so check both fields when you need to know why a monitor is silent. The dashboard marks such rows Over limit.

Where monitors live in the app

1. Open Sites in the left sidebar (/sites). Every monitor is a row; down monitors sort to the top.
2. Click Add Monitor to create one: pick a type, enter the address, adjust the settings groups, then Save.
3. Click a row (or its menu -> Edit) to open the monitor’s panel. The editor is split into collapsible groups: Main Settings (enabled switch, schedule, timeout, tags, Full Log, Open Stats, attached monitors), Monitoring Locations (locations, recheck strategy, fallback), Request Configuration and Response Validation (web types), Alert Subscriptions and Report Subscriptions.
4. Use the search box (Search by name or URL), the type, status and tag filters, and the view switcher (Full, Card, Grouped, Simple, Tall) to find monitors. The Grouped view groups rows by monitor type.

Read one monitor with the API or MCP

curl "https://api2.host-tracker.com/monitor/$MONITOR_ID" \
  -H "Authorization: Bearer $HT_TOKEN"

GET /monitor/{id} (scope monitor:read) returns the full configuration: expand=settings is its default. Add more with expand= (the list below); sending expand= replaces the default set, so include settings if you still want it. MCP: get_monitor (default expand settings,uptime).

Credentials inside settings (passwords, keys) are returned to the account owner and to subaccounts with edit rights; a view-only subaccount sees { "set": true, "updatedAt": ... } instead.

List, filter and search monitors

GET /monitor (scope monitor:read) returns a lean row per monitor - id, type, name, url, state, since, enabled, tags, updated, created, openStat, fullLog, cronSchedule and the expiry dates - inside the standard page envelope { "data": [...], "nextCursor": "...", "hasMore": true }.

# Down HTTP monitors tagged prod, 100 per page, with their settings and last incident
curl "https://api2.host-tracker.com/monitor?state=down&type=http&tag=prod&limit=100&expand=settings,lastIncident" \
  -H "Authorization: Bearer $HT_TOKEN"

Parameter	Values	What it does
q	Text	Case-insensitive substring match over name and address. No wildcards: * is taken literally.
type	One or more type tokens	Unknown tokens are refused with 422, never silently ignored.
state	up, down, paused, maintenance	Current state (see above).
enabled	true / false	The configured switch. Use state=paused to also catch over-limit monitors.
tag	One or more tags	A monitor matches if it carries any of the listed tags; each tag must match a whole tag. See Tags.
id	One or more monitor ids	Only these monitors.
includeId	One or more monitor ids	Always include these rows in addition to whatever the other filters match.
url + like	Address(es); like=true	Exact (case-insensitive) address match, or substring match with like=true. like without url is refused.
preset	bl:ru	Monitors built from a settings preset (the Russian blacklist check, stored as type: "http").
openStat	true / false	Monitors whose public statistics page is on or off.
updatedSince	Unix seconds, or a previous response’s syncCursor	Monitors created, changed state, or auto-disabled since then. A configuration edit or a manual pause does not move updated - subscribe to the monitor.updated webhook for those.
sort	name, state, type, interval, lastChange, url, tags, created, each optionally :asc / :desc; plus the one compound state,lastChange	Default created (newest first). state ascending puts down first, then maintenance, up, paused.
pausedLast	true	Moves every paused monitor after the rest, whatever the sort.
limit / cursor	1-500 (default 50) / the previous nextCursor	Paging. Stop when nextCursor is null. Send the same filters and sort with every page: a cursor replayed under a different sort (or pausedLast) answers 422 invalid_cursor, and changed filters give an inconsistent walk.
expand	See below	Adds blocks to each row or to the envelope.
from / to	Unix seconds	The window for uptime, spans and summary (default: the last 30 days).
fields	Comma-separated top-level member names	Returns only those members of each row (id is always kept). An unknown name answers 422 unknown_field.

Filters combine with AND. A list parameter can be repeated (type=http&type=ping) or comma-separated (type=http,ping). Long filter sets can be sent as a JSON body to POST /monitor/q instead.

expand values (the same list works on GET /monitor/{id}):

Value	Adds
settings	interval, slaTarget, locations, recheck, settings, attached
attached	attachedResults - the latest result of each attached sub-check
subscription	The monitor’s alert subscriptions with the contact identity
lastIncident	The last up/down transition
lastResult	The newest check result (add lastResult.metrics / lastResult.recheck for the decoded measurements and the recheck locations)
maintenance	The maintenance windows covering the monitor
uptime	Uptime percent over from/to
spans	Up/down spans in the window, plus disabledSpans (paused periods) and maintenanceSpans
summary	Envelope block: account-wide counts, by type, by tag, the tag list, top domains, downtime
count	Envelope block: { total, matched }

MCP: list_monitors takes q, state, type, tag, id, sort, limit (1-50, default 20) and cursor; use api_request for the parameters it does not expose (expand, fields, updatedSince…). list_monitor_types returns the type catalogue.

Limits and gotchas

• Unknown query parameters are refused (422 unknown_parameter), and so are unknown expand values (422 unknown_expand) - the error lists the allowed values.
• Deleted monitors simply disappear from the list; there is no tombstone. A client that mirrors your account should re-read the full list periodically or subscribe to the monitor.deleted webhook.
• uptime and response times are not sortable columns. To rank monitors by uptime, use GET /monitor/result/summary (MCP get_uptime_summary).

Related

• Anatomy of a check
• Monitor types
• Monitor settings reference
• REST API v2