Mastodon Instance Health Check Endpoint: How to Monitor With Uptime Kuma

You want to know if your Mastodon instance is reachable and responding to requests without logging in manually every hour. Mastodon provides a public health check endpoint that returns a simple JSON response when the server is running correctly. This article explains what the health check endpoint does, how to set up Uptime Kuma to monitor it, and what to do when the endpoint shows a problem.

Mastodon instances expose a /health path that returns HTTP 200 and an empty JSON object if the web server and database are operational. Uptime Kuma is a self-hosted monitoring tool that can poll this endpoint every few seconds and alert you when the status changes. By combining these two tools, you can detect downtime, slow responses, or configuration errors before they affect your users.

The following guide covers the health check endpoint specification, step-by-step Uptime Kuma configuration, and common monitoring pitfalls to avoid.

Why the Mastodon Health Check Endpoint Exists

Mastodon is a Ruby on Rails application that relies on a PostgreSQL database and a Sidekiq background job processor. The /health endpoint is a lightweight check that confirms the Rails application can connect to the database and return a response. It does not verify that Sidekiq is running, that media files are accessible, or that federation is working.

The endpoint is intentionally minimal. It avoids authentication because monitoring tools like Uptime Kuma need to check it without storing credentials. A successful response means the application server and database are alive. A failed response may indicate a crashed web server, a database connection pool exhaustion, or a deployment that has not completed.

Endpoint Specification

The health check endpoint is located at https://yourinstance.example.com/health. The response has these properties:

• HTTP status code: 200 on success, 500 or 503 on failure.
• Content-Type: application/json.
• Body: {} on success. On failure the body may be empty or contain an error message.

The endpoint does not require any headers, query parameters, or authentication tokens. Uptime Kuma can monitor it with a simple GET request.

Steps to Configure Uptime Kuma for Mastodon Health Monitoring

These instructions assume you have Uptime Kuma installed and accessible. If you have not installed it yet, deploy it on a server or a local machine using Docker or Node.js. The steps below use the web interface of Uptime Kuma version 1.23 or later.

1. Log in to Uptime Kuma and add a new monitor
   Open your Uptime Kuma dashboard in a browser. Click the Add New Monitor button on the top right. A configuration form appears.
2. Select the HTTP(s) monitor type
   In the Monitor Type dropdown, choose HTTP(s). This tells Uptime Kuma to send an HTTP GET request to the URL you provide.
3. Enter the Mastodon instance health check URL
   In the URL field, type https://yourinstance.example.com/health. Replace yourinstance.example.com with your actual Mastodon instance domain. Do not include any path after /health.
4. Configure the check interval
   Set the Interval to 60 seconds or longer. A 60-second interval balances timely detection with server load. For production instances, 120 seconds is also acceptable.
5. Set the expected HTTP status code
   Leave the Expected Status Code at the default value 200. Uptime Kuma will treat any non-200 response as a failure.
6. Enable SSL certificate validation if needed
   Check the Check Certificate box if you want Uptime Kuma to verify that the SSL certificate is valid and not expired. This is optional but recommended for production instances.
7. Add notification channels
   Scroll to the Notification section. Click Setup Notification and choose your preferred alert method. For example, select Telegram Bot and enter your bot token and chat ID. You can add multiple notification channels.
8. Save the monitor
   Click the Save button at the bottom. Uptime Kuma immediately starts polling the health endpoint. The dashboard shows a green status indicator if the check passes.

Common Monitoring Pitfalls and How to Avoid Them

Health check returns 200 but the instance is not serving users

The /health endpoint only verifies the application and database. It does not check Sidekiq, media proxy, or federation. If Sidekiq stops processing jobs, new posts and notifications will not appear even though the health check passes. To detect this, add a second monitor that checks the /api/v1/instance endpoint and validates the response body contains expected fields like uri and title. Set the expected status code to 200 and optionally add a keyword check for "uri":.

Monitor shows down but the instance is reachable from a browser

This usually happens when Uptime Kuma cannot resolve the instance domain or the network path is blocked. Verify that the Uptime Kuma server can resolve the domain using nslookup yourinstance.example.com. If Uptime Kuma runs behind a corporate firewall, ensure outbound HTTPS traffic to port 443 is allowed. Also check that the instance is not rate-limiting the Uptime Kuma IP address. Add the Uptime Kuma IP to the instance allowlist if necessary.

Uptime Kuma alerts are too frequent

A single failed health check may trigger an alert even if the instance recovers immediately. To reduce noise, set the Retry Interval in Uptime Kuma to 2 or 3. This means the monitor must fail multiple consecutive checks before it sends an alert. Go to the monitor settings, expand Advanced Settings, and set Retry Interval to 2. Also increase the Interval to 120 seconds to avoid false positives from transient network hiccups.

Item	Health endpoint only	Health + API endpoint monitoring
Coverage	Application server and database only	Application, database, API availability, and instance metadata
False positive risk	Low — endpoint is simple	Medium — API may fail due to caching or rate limits
Setup complexity	One monitor in Uptime Kuma	Two monitors with keyword checks
Alert accuracy	Misses Sidekiq and media failures	Catches more failure modes

The mastodon health check endpoint gives a reliable signal for basic server availability. For complete coverage, pair it with an API endpoint monitor that validates the response content. Uptime Kuma supports keyword checking in the response body, which allows you to confirm that the instance is returning expected data. Start with the health endpoint and add the API check after the first week of monitoring to tune the alert thresholds.

When the health check fails, investigate the Mastodon server logs at /var/log/mastodon/ or the systemd journal using journalctl -u mastodon-web. Common causes include a full disk, a database connection pool that is exhausted, or a stale Puma process that needs a restart. After fixing the issue, the health endpoint should return 200 within one polling interval.