# Monitors

A monitor is one thing checked on a schedule. There are eleven types; all of them share the same settings, states and confirmation rule.

## The types

| Type | Target | What it checks |
| --- | --- | --- |
| Website or API `http` | A URL | Sends a request (any method, headers, body, sign-in) and checks the answer. With no rules of your own it passes on any 2xx or 3xx status. |
| TCP port `tcp` | host:port | Connects to the port, with TLS if you ask. Can send a few bytes and check the banner that comes back. |
| Ping `ping` | A host or IP | Five pings: packets lost, average round trip, jitter. Fails when every packet is lost, or above the loss you set. |
| DNS `dns` | A domain | Looks up the record types you list (A, AAAA, CNAME, MX, TXT, NS, CAA) and tells you when the answer changes. With mail: true it also checks SPF and DMARC are there. |
| Certificate `cert` | A host | Reads the certificate: expiry, issuer, chain, hostname match, TLS version. Alerts at 30, 14, 7 and 1 days left. |
| Domain `domain` | A domain | Reads the expiry date, registrar and nameservers from the public registry (RDAP). Alerts at 30, 14, 7 and 1 days left. |
| MCP server `mcp` | A URL | The handshake, the sign-in flow, the tool, resource and prompt lists, changes to tools, and an optional safe test call. |
| AI gateway `gateway` | A base URL | The models list, then a tiny streamed reply from each model you pick: time to first token, tokens per second, which model answered. |
| Agent test `agent` | A chat endpoint | Sends your test questions and checks each answer with rules and an AI judge. |
| Heartbeat `heartbeat` | None | The other way round: your job calls us. You hear when it is late, fails or runs too long. |
| Service `service` | A status page URL | Reads a vendor’s Statuspage-compatible feed, so their incidents show beside yours. |

More on three of them: [MCP monitors](https://openping.ai/docs/mcp-monitors), [agent tests](https://openping.ai/docs/agent-tests) and [heartbeats](https://openping.ai/docs/heartbeats).

## What every monitor shares

- **How often.** From every 3 minutes on Free and every 30 seconds on paid plans, down to once a day.
- **Regions.** Where it is checked from. Leave it empty to use your organisation’s default regions.
- **Timeout.** 15 seconds unless you change it. A timeout is a failure with a clear reason, never a hang.
- **Severity.** `critical` and `normal` open an incident and alert; `low` goes into a daily digest.
- **Rules** (assertions), tags, a service to group it under, and an alert rule.

## Rules for websites and APIs

| Rule | Passes when |
| --- | --- |
| `status` | The status code is the one, or one of the ones, you expect |
| `latency` | The whole request took less than the time you set |
| `header` | A response header has the value you expect |
| `body_contains`, `body_not_contains` | The words are, or are not, in the response |
| `body_regex` | The response matches a pattern |
| `json_path` | A field such as `$.status` exists, equals or contains a value |
| `json_schema` | The JSON fits a schema (types, required fields, enums) |
| `size` | The response is no bigger than the size you set |
| `cert_days` | The certificate has at least this many days left |

When a rule fails, the result says so in words: “Expected status 200, got 503”.

## States

- **Up.** The last check passed.
- **Degraded.** It passed, but too slowly, or an agent’s pass rate fell below its target, or an MCP tool changed. The default slow line is three times the 7-day median, and at least 1 second, for 3 runs in a row.
- **Down.** A check failed and other regions confirmed it.
- **Paused** and **Maintenance.** Not being checked, on purpose.

## How a failure is confirmed

Each run goes out from one region, taking turns. When a run fails, two other regions retry at once. **Down needs two of the three to fail. Up again needs two passes in a row.** A monitor that flips more than 4 times in an hour is marked flapping, and its alerts fold into one.

## What each run keeps

Timings (DNS, connect, TLS, first byte, total), each rule’s result, the status code, the region, and the first 2 KB of the response with personal data removed. Samples are kept for 7 days; the numbers for 13 months.

## Secrets

A monitor never holds a key in plain text. Save the value once as a secret, then refer to it as `secret.NAME` anywhere a token or password goes. Values are write-only: nobody can read one back.

## Private addresses

Our probes only reach the public internet. A target on a private or reserved address is refused with a clear message. Private probes that run inside your network are planned.