Reference

Uptime monitors

Have Drumbeats call your public endpoint on a schedule and tell you when it stops answering properly.

The only monitor type where Drumbeats calls you:

curl -X POST https://api.drumbeats.io/v1/monitors \
  -H "X-API-Key: $DRUMBEATS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project-id>",
    "name": "Production API health",
    "type": "UPTIME_HTTP",
    "schedule": "5m",
    "uptime_url": "https://api.myapp.com/health",
    "uptime_expected_status": [200],
    "uptime_keyword": "\"status\":\"ok\"",
    "uptime_timeout_ms": 5000
  }'

curl -X POST https://api.drumbeats.io/v1/monitors \
  -H "X-API-Key: $DRUMBEATS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project-id>",
    "name": "Production API health",
    "type": "UPTIME_HTTP",
    "schedule": "5m",
    "uptime_url": "https://api.myapp.com/health",
    "uptime_expected_status": [200],
    "uptime_keyword": "\"status\":\"ok\"",
    "uptime_timeout_ms": 5000
  }'

Your service sends no pings. Drumbeats requests the URL on the interval you set and records what came back.

Use it for APIs, marketing sites, and health endpoints that should answer from the public internet. For internal jobs and queue workers, use Cron, Heartbeat, or Event-driven instead.

What each check records#

Every check stores the HTTP status code, the round-trip response time in milliseconds, an up or down verdict, and a failure reason when it failed. The reason is one of timeout, dns_failure, connection_refused, or ssl_error.

Configure the monitor#

Field	Required	Default	What it does
`uptime_url`	yes		The HTTP or HTTPS endpoint. Credentials in the URL are rejected, use `uptime_headers` instead
`schedule`	yes		Check interval as an interval string, such as `5m`
`uptime_method`	no	`GET`	`GET`, `HEAD`, or `POST`
`uptime_expected_status`	no	any `2xx`	Explicit list of acceptable status codes, such as `[200, 301]`
`uptime_keyword`	no	none	The response body must contain this string. Up to 1024 characters
`uptime_keyword_absent`	no	`false`	Set `true` to invert the keyword check, so the string must not appear
`uptime_headers`	no	none	Custom request headers as a JSON object. Use this for auth tokens
`uptime_request_body`	no	none	Request body for `POST` checks. Up to 10 000 characters
`uptime_timeout_ms`	no	`10000`	Per-request timeout. Must be between 1000 and 30 000
`uptime_follow_redirects`	no	`true`	Follow redirects before checking the status code
`uptime_verify_ssl`	no	`true`	Set `false` to accept self-signed or expired certificates
`failure_tolerance`	no	`1`	Failed cycles in a row before the monitor flips DOWN

Free accounts cannot check more often than every 60 seconds, paid plans every 30 seconds.

Hop-by-hop headers are rejected in uptime_headers because the HTTP layer controls them: host, content-length, transfer-encoding, connection, upgrade, keep-alive, trailer, te, expect, proxy-authorization, proxy-authenticate, proxy-connection.

Check the body, not just the status#

A 200 proves the web server answered. It does not prove the database behind it is reachable. Point the check at an endpoint that exercises the dependency and assert on the body:

-d '{
  "uptime_url": "https://api.myapp.com/health",
  "uptime_expected_status": [200],
  "uptime_keyword": "\"database\":\"ok\""
}'

-d '{
  "uptime_url": "https://api.myapp.com/health",
  "uptime_expected_status": [200],
  "uptime_keyword": "\"database\":\"ok\""
}'

A cached error page that returns 200 with the word maintenance in it fails the keyword check and pages you. A status-only check would call that healthy.

What happens when it breaks#

A single failed check does not page anyone. When a check fails, Drumbeats waits 5 seconds and tries again, up to 3 attempts total. Only when all three fail does the cycle count as a failure.

Situation	Incident event	Monitor status
Three attempts in a row fail, `failure_tolerance` reached	`FAILED`	DOWN
The TLS certificate crosses 30, 14, 7, or 1 day remaining	`SSL_EXPIRING`	Stays UP. Warning only
The Drumbeats probe itself is unreachable	none	Unchanged. Counted as unknown, never as your failure

Certificate warnings fire once per threshold crossed, not once per check, and they never flip the monitor DOWN. They give you a runway to renew rather than an outage. Renew the certificate and Drumbeats notices the new expiry date on the next check, clears the threshold history, and resolves any open SSL_EXPIRING incident on its own.

How you get alerted#

The incident pages every notification group on the monitor. The message carries the status code or failure reason.

When the next check passes, Drumbeats resolves the incident, flips the monitor to UP, and sends a recovery message to the same groups with the outage duration.

Reach Drumbeats through your firewall#

Checks come from a small set of static addresses. Allowlist them so your WAF does not filter the check and page you for its own blocking.

Check location	IP address
Europe (`eu-central`), the default	`37.120.185.240`
US East (`us-east`), beta	Not yet published

Every request also carries this User-Agent, which works if your filters match on that instead:

Drumbeats/1.0 (+https://drumbeats.io/docs/monitor-types/uptime)

Drumbeats/1.0 (+https://drumbeats.io/docs/monitor-types/uptime)

Check from more than one location#

By default a monitor is checked from eu-central only. In beta you can add us-east. Drumbeats opens an incident only when every checked location agrees the endpoint is down, which filters out a bad route from one vantage point. A location whose probe is unreachable counts as unknown, not as a failure.

Each location checks independently, so a two-location monitor costs 2 beats per cycle instead of 1.

The US East probe is not live in production yet and its egress IP is unpublished. If your firewall needs an exact list, allowlist the Europe address and leave us-east off that monitor.

Read check history#

# Latest result
GET /v1/monitors/<id>/check-results/latest

# Paginated history, 50 per page by default
GET /v1/monitors/<id>/check-results?page=1&limit=50

# Response-time stats over a window
GET /v1/monitors/<id>/response-time-stats?period_hours=24

# Latest result
GET /v1/monitors/<id>/check-results/latest

# Paginated history, 50 per page by default
GET /v1/monitors/<id>/check-results?page=1&limit=50

# Response-time stats over a window
GET /v1/monitors/<id>/response-time-stats?period_hours=24

The same data drives the monitor's status page when you publish one. Status pages show current state, 24 hour, 7 day, and 30 day uptime percentages, recent incidents, and response-time charts.

Next#

Monitor types covers when Uptime is the wrong choice. Status pages publishes this data. REST API monitors is the full CRUD reference.