Tag and organize your monitors

View as Markdown

Tags are free-text labels on a monitor - prod, client-acme, eu, payments. They cost nothing, need no setup, and make everything else easier once you have more than a handful of monitors: filtering the dashboard, picking a set for a bulk edit, scoping an API query or a report.

Settings reference

Setting (app label)	API field (v2)	Type / allowed values	Default	Plan limits	What it does for you
Tags (Main Settings)	`tags`	Array of non-empty strings; each is trimmed	None	None	The monitor’s full tag set. On update it replaces the set; `[]` or `null` clears it.
Tags to add (bulk edit)	`addTags` (update only)	Array of strings	-	None	Adds tags, keeping the monitor’s other tags.
Tags to remove (bulk edit)	`removeTags` (update only)	Array of strings	-	None	Removes tags (exact, case-sensitive match); a tag that is not there is ignored.
Default tags (Profile -> Defaults)	- (app only)	Comma-separated text	None	None	Tags every monitor created in the app starts with.

The rules

A tag is a whole string. Filtering by prod matches monitors tagged prod, not production or prod-eu.
Commas separate tags. In the app, typing a comma (or pressing Enter) closes the current tag. Tags are stored as one comma-separated list, so a comma sent inside a tag through the API is read back as two tags. Don’t put commas in tags.
No wildcards in tag filters. Characters such as *, %, _ and [ are matched literally: tag=50% finds the tag 50% and nothing else.
Case. Removing a tag matches it exactly, including case, so Prod and prod are different tags to removeTags. Pick one spelling and stick to it.
Blank tags are refused (422 validation_failed, reason: "empty"); surrounding spaces are trimmed.
No registry. A tag exists while at least one monitor carries it. The list of tags in use comes from GET /monitor?expand=summary (summary.tags).

Set it up in the app

Tag one monitor

On Sites, open the monitor (or Add Monitor) and expand Main Settings.
In Tags, type a tag and press Enter or type a comma. Repeat for more tags; click a tag’s x to remove it.
Save.

Filter by tag - on Sites, open the tag filter (Filter by tags) and pick one or more tags. A monitor is shown if it carries any of the selected tags; the tag filter combines with the type and status filters and the search box.

Add or remove a tag on many monitors - select them on Sites, click Edit, fill Tags to add and/or Tags to remove under Monitor Settings, then Update. Each monitor keeps its other tags. See Bulk operations.

Do it with the API or MCP

# Create with tags
curl -X POST https://api2.host-tracker.com/monitor \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "type": "http", "url": "https://shop.example.com/", "interval": 300,
        "locations": { "pools": ["allworld"] }, "tags": ["prod", "shop"] }'

# Add one tag and remove another, leaving the rest alone
curl -X PATCH "https://api2.host-tracker.com/monitor/$MONITOR_ID" \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "addTags": ["eu"], "removeTags": ["staging"] }'

# Every monitor tagged prod OR eu
curl "https://api2.host-tracker.com/monitor?tag=prod,eu" -H "Authorization: Bearer $HT_TOKEN"

# Tag every monitor tagged "shop" with "payments" (asynchronous job)
curl -X POST https://api2.host-tracker.com/monitor/bulk-update \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: tag-shop-payments-1" \
  -d '{ "filter": { "tags": ["shop"] }, "patch": { "addTags": ["payments"] } }'

tag on GET /monitor and filter.tags on the bulk operations both mean “any of these tags”.
sort=tags orders monitors by their tag list compared as text - in practice by the first tag alphabetically; untagged monitors come first.
expand=summary adds summary.byTag (counts per tag) and summary.tags (all tags in use).
MCP: create_monitor (tags, comma-separated), update_monitor (tags replaces, addTags / removeTags edit), list_monitors (tag), bulk_update_monitors (filterJson {"tags":["shop"]}, patchJson {"addTags":["payments"]}).

Limits and gotchas

tags together with addTags or removeTags in one body is refused (422, reason: "conflicts_with_tags") - send the replacement or the edits, not both.
addTags / removeTags on a create are refused (reason: "update_only"); use tags.
A tag named in both addTags and removeTags ends up removed.
Changing tags does not move a monitor’s updated timestamp, so GET /monitor?updatedSince= will not report it; use the monitor.updated webhook to follow configuration edits.