How your account is organised

This page describes every object your HostTracker account holds, how the objects point at each other, and which API call reads each one. Read it before you automate anything: most “why did nothing happen” questions come from a missing link between two objects (a monitor with no subscription, a contact that was never confirmed).

The objects at a glance

flowchart LR
    ACC[Account] --> MON[Monitor]
    ACC --> CON[Contact]
    ACC --> GRP[Contact group]
    ACC --> MW[Maintenance window]
    ACC --> SP[Status page]
    ACC --> WH[Webhook]
    ACC --> TOK[API token]
    ACC --> MEM[Shared-access member]
    MON --> ATT[Attached sub-check]
    MON --> RES[Check result]
    MON --> INC[Incident / down span]
    MON -- alert subscription --- CON
    MON -- report subscription --- CON
    GRP -. preset of .-> CON
    MW -- covers --> MON
    SP --> CMP[Component]
    CMP -- shows --> MON
    SP --> SPI[Status page incident]
    SPI --> UPD[Timeline entry]
    SP --> SUB[Subscriber]
    SP --> TPL[Template]
    CON --> NOT[Notification]
    WH --> DEL[Delivery]
    ACC --> JOB[Job]
    JOB -. produces .-> REP[Generated report]

Rules that hold for every object

• Ids are opaque. Most are GUIDs; results, incidents, notifications, subscriptions and generated reports use prefixed string ids (res_..., inc_..., alt_..., als_..., rsub_..., rep_...). Pass them back exactly as you received them; never build or parse one.
• Everything is private to the account. An id that belongs to another account answers 404 not_found, the same as an id that does not exist.
• Timestamps are Unix seconds on every read and write. Intervals and durations are also in seconds, except the alert delay on a contact, which is in minutes.
• Scopes. Every API call needs one scope (for example monitor:read). See API authentication, tokens and scopes.
• Deletes are permanent. The API answers a delete with a receipt of what was removed (cascaded counts). There is no trash or undo.

Account and shared access

What it is. Your HostTracker account: login, profile, time zone, language, plan (package), usage against the plan’s limits, and the default monitoring locations new monitors start with. Teammates get shared access (subaccounts) with a set of rights instead of your password.

• Id: the account id (GET /account -> id). A shared-access member is identified by the contact it was granted to.
• Links: owns every other object on this page. A member’s rights are tokens such as monitor:write, contact:read, billing:read, profile:write, api:access, member:write, statusPage:read.
• Read: GET /account (identity, plan, usage, limits including the allowed check intervals, flags), GET /account/usage, GET /account/quota (API quota and the scopes your token carries), GET /account/member (shared-access members). Scope account:read. MCP: get_account, get_account_usage, get_account_quota.
• Lifecycle: the account is created by signing up. PATCH /account (scope account:write) changes name, company, phone, country, time zone, language and default locations. Members are invited and removed in the app under Shared access (/access); there is no API for that. Plan changes and payments are app-only.

See Account and billing overview and Invite teammates with subaccounts.

API token

What it is. A bearer token that lets a script, SDK, CLI or AI assistant act on the account with a chosen set of scopes, an expiry and an optional IP allow list. An MCP client can instead connect with OAuth, which issues short-lived tokens behind the scenes.

• Id: none you can read through the API. The token value is shown once, when you create it.
• Links: belongs to the account; its scopes decide which of the calls on this page it may make.
• Read: GET /account/quota lists the scopes the calling token carries.
• Lifecycle: created and deleted in the app at Integrations -> API (/integrations/api); OAuth connections are revoked under Connected apps on the same page. Tokens cannot be created through the API. OAuth connections are never granted the account scope family.

Monitor

What it is. One recurring check of one target: a type (http, ping, port, api, waterfall, cntCheck, tran, dnsbl, domainExp, sslExp, webRisk, counter, database, snmp), a url or host, a schedule (interval in seconds or a cronSchedule), locations, type-specific settings, tags, and a state (up, down, paused, maintenance).

• Id: GUID.
• Links: has attached sub-checks, check results, incidents and state spans; is linked to contacts by alert and report subscriptions; can be covered by maintenance windows; can appear as a component on status pages; can be in a webhook’s scope.
• Read: GET /monitor (list, filter by type, tag, state, q, url, enabled…), GET /monitor/{id} (full configuration). Add expand= for related data: settings, subscription, lastResult, lastIncident, uptime, spans, maintenance, attached. Scope monitor:read. MCP: list_monitors, get_monitor.
• Lifecycle: create POST /monitor; change PATCH /monitor/{id}; pause or resume PATCH with "enabled": false|true; delete DELETE /monitor/{id} (removes its alert, report and maintenance subscriptions); copy POST /monitor/{id}/copy; many at once through the bulk jobs. The type cannot be changed after creation. Scope monitor:write.

Field-by-field detail: Monitor fields by type. Concepts: What a monitor is.

A monitor created through the API alerts nobody

A monitor created in the app is subscribed to your contacts by default. A monitor created with POST /monitor, create_monitor or a bulk job has no subscriptions unless the request adds them (alertSubscriptions, reportSubscriptions) or you add them afterwards. Location-based types also need locations.pools in the create request.

Attached sub-check

What it is. A blacklist (DNSBL), certificate expiry, domain expiry or Web Risk check that rides on a parent monitor instead of being a monitor of its own. Website/HTTPS monitors take all four; Ping and Port monitors take DNSBL only.

• Id: none of its own - it is addressed through the parent monitor.
• Links: belongs to one monitor; its alerts go to that monitor’s subscribed contacts.
• Read: GET /monitor/{id}/attached (current result per kind), or expand=attached on a monitor read. MCP: get_monitor with expand="attached".
• Lifecycle: switched on and off with the monitor’s attached member ({"attached": {"sslExp": true}}) on create or PATCH /monitor/{id}. Blacklist zones can be muted with POST /monitor/{id}/attached/dnsbl/mute. Removed with the parent.

See Attach sub-checks to a monitor.

Contact

What it is. A destination for alerts and reports: an email address, a phone number for SMS or voice calls, a messenger chat (Telegram, Viber, Discord and others), a browser for web push, or an HTTP endpoint (the webhook alert contact used for Slack, Teams, PagerDuty and similar). It carries a language, an alert delay, active hours and grouping options.

• Id: GUID.
• Links: linked to monitors by alert and report subscriptions; can be a member of contact groups; receives notifications.
• Read: GET /contact, GET /contact/{id} (expand=subscription, group, template), GET /contact/type (the types and what each can do). Scope contact:read. MCP: list_contacts, get_contact.
• Lifecycle: create POST /contact (email, sms, voiceCall, http and webPush through the API; messenger contacts are created by connecting the messenger bot in the app). Email, SMS and voice contacts start unconfirmed and receive nothing until confirmed with the code they were sent (POST /contact/{id}/confirmation/verify; resend with POST /contact/{id}/confirmation). Change with PATCH /contact/{id} (a new address needs confirming again), test with POST /contact/{id}/test, delete with DELETE /contact/{id} (removes all its subscriptions). Scope contact:write.

See What a contact is.

Contact group

What it is. A named set of contacts, each with the events it should get (up, down, repeatedlyDown, daily, weekly, monthly, quarterly, yearly). A group is a preset: applying it to monitors writes ordinary subscriptions once. It keeps no live link to those monitors and subscribes nobody by itself.

• Id: GUID.
• Links: lists contacts; nothing points back at it after it has been applied.
• Read: GET /contact/group, GET /contact/group/{id}. Scope contact:read. MCP: list_contact_groups.
• Lifecycle: POST /contact/group, PATCH /contact/group/{id} (a new member list replaces the whole set), DELETE /contact/group/{id} (contacts stay). A contact’s own memberships: PUT /contact/{id}/group.

See Group contacts and subscribe them together.

Alert subscription

What it is. The link that makes a monitor alert a contact: one (monitor, contact) pair plus the set of alert types it carries - down, up, repeatedlyDown (still-down reminders).

• Id: the pair itself (/monitor/{monitorId}/alert/{contactId}). The flat account-wide list also gives each pair an als_... id.
• Links: one monitor, one contact.
• Read: per monitor GET /monitor/{id}/alert (scope monitor:read), per contact GET /contact/{id}/alert (contact:read), whole account GET /alert, /alert/by-monitor, /alert/by-contact (subs:read). MCP: list_subscriptions.
• Lifecycle: set a pair with PUT /monitor/{monitorId}/alert/{contactId} {"alertTypes": ["down","up"]} - the set replaces the previous one. Remove with DELETE on the same path, or all of a monitor’s with DELETE /monitor/{id}/alert. Many pairs in one transaction: POST /alert/bulk. MCP: subscribe_contact, unsubscribe_contact.

Report subscription

What it is. The link that sends a contact a scheduled uptime report about a monitor: one (monitor, contact) pair plus frequencies (daily, weekly, monthly, quarterly, yearly). Email contacts only.

• Id: the pair (/monitor/{monitorId}/report/{contactId}); the flat list gives an rsub_... id.
• Links: one monitor, one email contact.
• Read: GET /monitor/{id}/report, GET /contact/{id}/report, GET /report (+ /by-monitor, /by-contact, /report/{id}). MCP: list_subscriptions with kind="report".
• Lifecycle: PUT /monitor/{monitorId}/report/{contactId} {"frequencies": ["weekly"]}, DELETE on the same path, POST /report/bulk. Frequencies your plan does not include are refused. MCP: subscribe_contact with frequencies.

See Subscriptions - alert vs report and Schedule report subscriptions.

Maintenance window

What it is. A planned period (one-off, or weekly on chosen days) during which the covered monitors hold back alerts and/or keep the time out of uptime statistics. Suppression is chosen per monitor (alerts, stats).

• Id: GUID.
• Links: covers an explicit list of monitors; can be shown on status pages (showOnStatusPage).
• Read: GET /maintenance (filter by state: scheduled, active, finished), GET /maintenance/{id}, GET /monitor/{id}/maintenance. Scope monitor:read. MCP: list_maintenance.
• Lifecycle: POST /maintenance, PATCH /maintenance/{id} (a new monitor list replaces the coverage), DELETE /maintenance/{id} (cancelling an active window makes its monitors alert again at once). Scope monitor:write. MCP: create_maintenance, update_maintenance, delete_maintenance.

See What a maintenance window is.

Status page and its parts

What it is. A public page at its own address that shows the health of chosen services, with its own branding, settings and audience. It has four kinds of child object:

• Component - one row on the page. Either shows a monitor’s live state (monitorId) or is a third-party component whose state you set by hand (manualState: operational, degraded, down). Id: GUID.
• Status page incident - an incident or scheduled maintenance you declare on the page (kind: incident or maintenance), with a title, impact (minor, major), affected components and a lifecycle state (investigating, identified, monitoring, resolved). Id: GUID.
• Timeline entry (update) - each message posted on a status page incident, with the state it moved to. The timeline is append-only; posted messages cannot be edited.
• Subscriber - someone following the page: an email address (joins only through the public page’s double opt-in) or a Slack, Teams or webhook channel you add. Id: GUID.
• Template - a saved title, message and default impact for announcements you post often. Id: GUID.

Reading and writing:

• Read: GET /statuspage, GET /statuspage/{id} (settings and components), GET /statuspage/{id}/incident, GET /statuspage/{id}/incident/{incidentId}, GET /statuspage/{id}/subscriber, GET /statuspage/{id}/template. Scope statuspage:read. MCP: list_status_pages, get_status_page.
• Lifecycle: POST /statuspage (public at its slug immediately; the slug cannot change later), PATCH /statuspage/{id}, PUT /statuspage/{id}/component (replaces the whole component set), DELETE /statuspage/{id} (removes components, incidents, subscribers and templates). Declare with POST /statuspage/{id}/incident, post updates with POST /statuspage/{id}/incident/{incidentId}/timeline - both notify subscribers. Scope statuspage:write.

See Status pages overview.

Two different “incidents”

A monitor incident is recorded automatically when a monitor goes down and closes when it recovers (GET /monitor/incident). A status page incident is an announcement a person declares on a public page (POST /statuspage/{id}/incident). Declaring one does not change any monitor. A monitor’s outages show on a status page only through its component (state, uptime bars and outage details, depending on the page’s features), never as an announcement.

Monitor incident and state span

What it is. An incident is one down episode of a monitor: from the confirmed down transition to the confirmed recovery. It has a start, an end (for an open incident, the last moment the monitor was seen down), a duration, a severity band (minor under 5 minutes, major 5 to 60 minutes, critical 1 hour or more), the error that caused it, whether it began inside a maintenance window, and an optional comment. A state span is one continuous up or down period; every down span names its incident.

• Id: incident inc_...; spans have no id of their own.
• Links: belongs to one monitor; groups the check results recorded during it.
• Read: GET /monitor/incident (whole account), GET /monitor/{id}/incident, GET /monitor/incident/{id} (with its timeline), GET /monitor/incident/{id}/check (the failing checks, plan feature), GET /monitor/{id}/span. Scope monitor:read. MCP: list_incidents, get_incident.
• Lifecycle: opened and closed by the monitoring itself. You can only add a comment (POST /monitor/incident/{id}/comment; MCP comment_incident) or wipe a monitor’s statistics (POST /monitor/{id}/reset-stats).

See What is an incident.

Check result

What it is. One logged check: when it ran, from which location, up or down, how long it took, the error for a failure, measurements (response time and its phases, and type-specific values), and a page snapshot when one was captured. Consecutive identical results are stored as one row with a checkCount.

• Id: res_..., addressed together with its monitor (/monitor/{monitorId}/result/{id}).
• Links: belongs to one monitor; may fall inside an incident.
• Read: GET /monitor/{id}/result, GET /monitor/result (across monitors), GET /monitor/{id}/result/{resultId}, GET /monitor/{id}/result/{resultId}/snapshot. One request covers at most 30 days. Scope monitor:read. MCP: list_monitor_results.
• Lifecycle: written by the monitoring. Read-only.

See Reading a monitor’s results and incidents.

Notification

What it is. One message HostTracker delivered (or tried to deliver) to a contact - an alert, a reminder, a test or a scheduled report - with its outcome (sent, blocked, sendFailed and similar).

• Id: alt_....
• Links: one contact, usually one monitor.
• Read: GET /contact/notification, GET /contact/{id}/notification, GET /contact/notification/{id} (with the rendered content), GET /contact/notification/summary (counts per contact and day). Scope contact:read.
• Lifecycle: written by the alerting. POST /contact/notification/resend re-sends a scheduled report for a past period.

Generated report

What it is. An uptime document (PDF, CSV, XML or HTML) over chosen monitors and a time range, produced on request. Scheduled reports sent to contacts are report subscriptions, not this object.

• Id: rep_.... It stays downloadable for 7 days.
• Links: covers a list of monitors; produced by a job.
• Read: GET /monitor/report/{id} (what it covers), GET /monitor/report/{id}/content (the file). Scope monitor:read. The catalogue of types, formats and sections: GET /report/type.
• Lifecycle: request with POST /monitor/report (scope monitor:write, Idempotency-Key required); the answer is a job. MCP: generate_report, then wait_for_job.

Job

What it is. The record of an asynchronous operation: bulk monitor or contact writes, bulk deletes, statistics resets, large copies and report generation answer 202 with a job instead of a result.

• Id: GUID.
• Links: points at the items it created, changed or deleted (per-item entityId, status and result).
• Read: GET /job/{id} (state, progress, summary, per-item results), GET /job (recent jobs). The scope is the one the operation that created it needed. MCP: get_job, wait_for_job.
• Lifecycle: queued -> running -> one of succeeded, partial (some items failed), failed, cancelled. interrupted means the server running it stopped; continue it with POST /job/{id}/resume. Cancel with POST /job/{id}/cancel (items already done are not rolled back). A job stays readable until its expiresAt.

See Bulk operations on monitors.

Webhook

What it is. A signed HTTPS delivery of account events (monitor.down, monitor.up, incident.opened, monitor.created, certificate.expiring and others) to your own endpoint, for integrations. It is a different object from a webhook alert contact, which receives ordinary alerts in a template you design.

• Id: GUID. Each delivery has its own id (d_...).
• Links: scoped to the whole account, a list of monitors, or tags.
• Read: GET /webhook, GET /webhook/{id}, GET /webhook/{id}/delivery (recent deliveries and their outcome). Scope webhook:read. MCP: list_webhooks, list_webhook_deliveries.
• Lifecycle: POST /webhook (the signing secret is returned once), PATCH /webhook/{id}, DELETE /webhook/{id}, POST /webhook/{id}/test, POST /webhook/{id}/delivery/{deliveryId}/redeliver. After 20 consecutive failures a webhook disables itself. There is no webhook page in the app.

See Webhooks and Webhook events reference.

Instant check

What it is. A one-off check of a url or host from HostTracker’s locations, with no schedule and no alerts.

• Id: a pair - dbId (integer) and id (GUID).
• Read: GET /check/{dbId}/{id}, GET /check (history). Scope check:read. MCP: get_check_result.
• Lifecycle: POST /check (scope check:write; MCP run_instant_check). Results are read-only.

See Instant checks vs monitors.

Related

• Do anything in HostTracker: task map
• Monitor fields by type
• Build reports and summaries
• REST API v2