Check types

This page explains the seven check types, what each one checks, and when to use it.

Every check runs from Cloudflare's network on the monitor's interval. HTTP, Keyword, and API checks report up, slow, or down. The other four report up or down only.

#The HTTP family: HTTP, Keyword, API

These three share one engine: an HTTP request on your interval, judged in a fixed order. A transport failure (a timeout, a refused connection, or a certificate problem) is down. Then the status is checked. Then every content rule. A check that passes all of that but takes at least the slow threshold is slow.

• HTTP judges the status code. With Expected status on Automatic, any code below 400 passes, including redirects. Set a code and only that code passes.
• Keyword adds text rules: the body must contain, or must not contain, the strings you set. A page that returns 200 and renders an error still fails. A keyword monitor needs at least one rule.
• API adds JSON field rules, such as status equals ok, so you watch a health endpoint's real signal instead of its status code.

All three default to a HEAD request. A monitor with content rules reads the body, so it uses GET instead and follows redirects. Request headers, request bodies, and content rules are covered in Requests and rules.

#Heartbeat

Every other check reaches out to your systems. A heartbeat waits for your system to reach in. Each heartbeat monitor gets a ping URL, and your cron job, worker, or backup script calls it at the end of every run:

curl -fsS -m 10 https://api.uptimex.co/v1/heartbeats/<id>/ping

GET and POST both count, and the URL needs no authentication, so treat it as a secret. The rules:

• Set Expected every to the gap between runs, up to 7 days, and Grace to how late a ping may be. The monitor goes down when the last ping is older than the interval plus the grace, and alerts at once.
• A new heartbeat stays pending until its first ping. The first ping does not alert. Any later ping while the monitor is down marks it up and sends the recovery alert.
• While the monitor is up, pings within half the interval of the last one (at most 60 seconds) are ignored, so a job that pings twice does no harm.
• A paused heartbeat answers its ping URL with 404.

Set the grace to the job's worst normal runtime. A nightly backup that usually takes 5 minutes but sometimes 20 wants a daily interval with a 30 minute grace.

#In cron

Append the ping to the job itself, so it only fires when the job succeeded:

0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://api.uptimex.co/v1/heartbeats/<id>/ping

#In CI

Add a final step that only runs when the workflow is green:

- name: Ping UptimeX
  if: success()
  run: curl -fsS -m 10 https://api.uptimex.co/v1/heartbeats/<id>/ping

#Scheduler

A scheduler is the inverse of a heartbeat: UptimeX calls your URL on the interval. Point it at an endpoint that does work when called, such as a cleanup route, a report generator, or a queue drain, and the schedule and the alerting come together. The rules are stricter than an HTTP check:

• Only a 2xx response is a pass. A 3xx, a 4xx, a 5xx, a timeout, or a connection error is a miss. Redirects are never followed.
• Each run's result is the status. There is no failure threshold, and a miss alerts at once.
• The method is POST by default, or PUT, PATCH, or DELETE. Headers, a body, and the timeout (10 s by default) can be set in Monitor settings after creation.

The endpoint is now callable on a schedule, so protect it: require a secret in a request header, set that header on the scheduler, and reject calls without it.

#Port

A port monitor opens a TCP connection to a host and port on your interval. Nothing is sent and nothing is read: success is that the port accepted the connection, and the connect time is recorded as the latency. The host can be a hostname or a public IPv4 address. The timeout defaults to 10 s, and the failure and recovery thresholds apply.

Use it for anything that listens on a port but does not speak HTTP: databases, mail servers, game servers, SSH. It answers whether the service accepts connections, not whether it is healthy, so pair it with an HTTP or API check when the service has a health endpoint. A host behind a proxy that terminates TCP, such as a Cloudflare-proxied domain, wants an HTTP monitor instead.

#DNS

A DNS monitor resolves one record on your interval and fails when resolution fails or returns no records. Record types: A, AAAA, CNAME, MX, TXT, and NS. Set an expected value and the check also fails when no answer contains it, which catches a hijacked or mistyped record, not only a missing one. The target must be a hostname, not an IP address.

Two moments it earns its keep: during a DNS migration, point it at the record with the new value as the expected answer and watch the cutover land; and permanently on your apex domain, where a surprise change is exactly the alert you want. The monitor page keeps the most recent answers, so you can see what the record said, not only that it differed.

#What's next?

• Create a monitor: every field and its default.
• Requests and rules: headers, bodies, and content rules.
• When alerts fire: how a failed check becomes an alert.