Monitors

A monitor checks one thing at an interval, from the locations you pick. Create one with new monitor on the dashboard; test runs the check once from the selected locations without saving.

Paste a curl command in the URL field of an HTTP monitor to fill in the method, headers and body.

HTTP monitors also take a method, request headers and body, the accepted status codes and whether to skip TLS verification. Agents older than a check type report unknown monitor type: update them.

HTTP and keyword monitors can check the JSON body of the response, for example a health endpoint that returns {"status": "ready", "checks": {"redis": {"status": "ok", "latencyMs": 3}}}. Add rules under response checks: all must pass, otherwise the check fails and the result, the incident and the alert say which rule broke, e.g. checks.redis.status: expected "ok", got "error".

• Paths use dots and brackets: a.b, items[0] (or items.0, items[-1] for the last one), ["key.with.dots"]. A leading $. is allowed.
• Operators: equals, not equals, contains (substring, array element or object key), not contains, exists, not exists, >, >=, <, <= (numbers) and matches (regular expression).
• Values are compared by type: numbers as numbers (3 equals 3.0), true / false / null by name, objects and arrays as JSON.
• Rules run on agents too. Agents older than this feature fail the check with "update it" instead of passing it unchecked.

HTTP and keyword checks measure where the time goes: DNS lookup, connect, TLS handshake, wait for the first byte (the server at work) and transfer of the body. On the monitor page switch the response time chart to by phase, per location or all together; hover a latency in the check log for the breakdown of that check. With redirects the phases of every hop are added up.

The monitor page also shows uptime and response time percentiles (p50, p95, p99) for any period, compared with the period before. Drag on the chart to zoom in.

A monitor is degraded when some of its locations fail, but not more than half. The share that counts is set in settings → monitors (35% by default) and can be changed per monitor, up to 50%. Degraded opens no incident and counts as up for uptime; channels can get it as an event (off by default).

A monitor can also turn degraded when it answers too slowly. Set the slow threshold:

• off (default);
• fixed, in ms (below the timeout): a location is slow when the median of its last 3 successful checks is above it, so one spike changes nothing;
• automatic: each location gets its own threshold, 3 times its usual response time and at least 100 ms more. The usual time is the median of its hourly averages over the last 7 days, so a far-away agent has its own baseline. It starts once a location has 24 hours of history.

Slow locations count like failing ones toward the degraded share, never toward down. With one location, being slow is enough. The response time chart draws the threshold as a dashed line, and the alert says which location was slow and by how much. For heartbeat monitors the threshold applies to the ping= duration.

Every check type works over IPv6, and hosts with only AAAA records just work. Put IPv6 addresses in brackets when a port follows: [2001:db8::1]:443 (tcp), https://[2001:db8::1]/, redis://[2001:db8::1]:6379, grpc://[2001:db8::1]:50051. Ping and dns take the bare address (2001:db8::1); ping uses ICMPv6.

ip version sets how a check treats a host with both IPv4 and IPv6:

The hub and every agent test whether they reach the Internet over IPv6; the agents page and the monitor form show the result. A location without IPv6 cannot be chosen for IPv6 only or IPv4 and IPv6; IPv4 or IPv6 and the instance default check over IPv4 there. TLS certificate expiry is read over either family. For Docker, see IPv6 in Docker.

Passwords in connection URLs are hidden in the monitor list, from read-only users and in alerts; use a read-only database user. PostgreSQL, MySQL and MongoDB use TLS when the server offers it.

Docker checks talk to the Docker Engine of the location that runs them: the hub or the agent needs /var/run/docker.sock (or DOCKER_HOST). With Docker, add -v /var/run/docker.sock:/var/run/docker.sock:ro to the hub or agent container (the entrypoint lets the pingtxt user use it). For an agent installed with systemd, allow it with sudo systemctl edit pingtxt-agent:

Access to the Docker socket is equivalent to root on that machine (:ro does not limit the API). pingtxt only reads GET /containers/<name>/json, but enable it only where you need container checks.

A monitor of type mcp server checks a remote Model Context Protocol server. (To let AI assistants use pingtxt itself, see the MCP server of the hub.)

Each check runs initialize, sends notifications/initialized, then tools/list (all pages) when the server advertises tools or a tool condition is set, and finally deletes the session. Tools are never called. The result shows the server name and version, the protocol version, the transport and the tool count, e.g. my-server 1.4.0 · mcp 2025-06-18 · streamable · 12 tools. https endpoints get certificate expiry alerts.

For jobs that run on a schedule (backups, cron, queues), create a monitor of type heartbeat (push). It gets a secret URL; the job calls it at the end of every run, with any HTTP method:

The monitor goes down when no call arrives within the expected period plus the grace time, and back up at the next call. Optional query parameters: status=down reports a failed run, msg= stores a short note, ping= the run time in ms. The URL uses the public URL from the settings and can be regenerated from the monitor page.

A monitor sits in one group (or none) and has any number of colored tags. Manage them on the groups page. Then:

• filter the dashboard by group or tag, and show groups as sections;
• add whole groups to a status page: monitors added to the group later show up too;
• pick monitors by group or tag in maintenance windows and notification channels;
• filter the API: GET /api/monitors?group=<id> (or group=none) and ?tag=<id>.

At the first failure of a check, the location that ran it collects diagnostics right away and sends them with the failed result, so they are ready when the alert goes out:

• DNS: the A/AAAA answers (and CNAME) of the system resolver; for DNS monitors also the answer of their server and the NS records of the name;
• TCP: a connection to each resolved address (up to 4) on the monitor's port;
• TLS: version, certificate subject, issuer, names, expiry and the verification error;
• HTTP: status, redirects (without query strings) and response headers. Cookies, Authorization and any header whose name contains token, key, secret, session, csrf or auth are redacted. The body and the request headers are never kept;
• traceroute: up to 20 hops with reverse names, as TCP SYNs to the monitor's port (UDP for ping and DNS). It needs no root: on Linux it reads the ICMP errors like tracepath, so it works in the non-root containers. Other systems skip it for now.

It takes at most 8 seconds and 16 KB, and runs at most once every 10 minutes per monitor and location. The first alert of an incident lists one line per failing location and links to the full diagnostics on the incidents page; webhooks get diagnostics and diagnostics_url, reminders only the link. Diagnostics are never shown on status pages. They are also in the API (GET /api/incidents/{id}/diagnostics) and the MCP tool get_incident_diagnostics.

Turn them off in settings → monitors, or per monitor. Diagnostics of incidents are kept 30 days (configurable); those of failures that never became an incident, one day.

settings → data → import from uptime kuma reads a backup file of Uptime Kuma 1.x (Settings → Backup → Export there) and shows what will be created before anything changes. Groups and tags come along and paused monitors stay paused; notification channels are not imported.