Add a Live Uptime Badge to Your GitHub README
Published May 2026 by SiteInformant Team
Add a Live Uptime Badge to Your GitHub README
A README badge is useful when it answers a real question at a glance: is the thing behind this repository up right now?
Build badges tell people whether CI passed. Package badges tell people what version is published. A live uptime badge does something different: it checks the public endpoint that users, customers, bots, docs, or demo environments actually touch.
Here is the basic Markdown pattern:
[](https://api.siteinformant.com/api/public/status/page/api.example.com%2Fhealth)
Replace api.example.com%2Fhealth with the public endpoint you monitor. If you monitor a root domain, use the domain only:
[](https://api.siteinformant.com/api/public/status/page/example.com)
That gives your README a small live badge that links to a public status page with more detail.
What the Badge Should Monitor
Use an endpoint that represents the thing your repository promises.
For an API library, monitor the API health endpoint:
api.example.com/health
For a demo app, monitor the deployed demo:
demo.example.com
For documentation, monitor the docs host:
docs.example.com
Try not to point the badge at an internal-only service, a local development URL, or a synthetic endpoint that always returns OK while the real application is broken. The badge is most useful when it reflects the path a real user would notice.
Step 1: Create a Public Uptime Check
Create a monitor for the site, API, docs page, or demo URL you want represented in the README.
In SiteInformant, public badges are tied to public status checks. Once the monitor exists, enable the public badge/status option for that endpoint. You can use a domain like example.com or a host plus path like api.example.com/health.
If the target includes a path, URL-encode the slash in the badge URL:
api.example.com/health
api.example.com%2Fhealth
Step 2: Copy the Markdown Badge
The README badge has two parts:
- The badge SVG image:
https://api.siteinformant.com/api/public/status/badge.svg/{target} - The public status page:
https://api.siteinformant.com/api/public/status/page/{target}
Put them together like this:
[](https://api.siteinformant.com/api/public/status/page/{target})
You can also choose a badge style:
[](https://api.siteinformant.com/api/public/status/page/{target})
[](https://api.siteinformant.com/api/public/status/page/{target})
[](https://api.siteinformant.com/api/public/status/page/{target})
For most READMEs, flat-square fits cleanly beside build, license, and package badges.
Step 3: Put It Near the Top of the README
Badges work best when they are visible without turning the README into a dashboard.
A simple layout:
# Example API
[](https://api.siteinformant.com/api/public/status/page/api.example.com%2Fhealth)
[](https://github.com/example/example-api/actions)
Small API client for Example API.
The uptime badge sits beside CI, but it answers a different question. CI says the code passed tests at build time. Uptime says the public service is reachable now.
Step 4: Link to Useful Status Details
Avoid linking the badge image to itself. Link it to a public status page so readers can inspect details when the badge is not green.
A good status page helps answer:
- Is the endpoint down or just slow?
- When was the last check?
- Has this been happening repeatedly?
- Is SSL still valid?
- Which endpoint is this badge actually checking?
That context matters when someone is deciding whether to open an issue, wait, retry, or investigate their own network.
Common README Badge Mistakes
The most common mistake is using an uptime badge as decoration. If nobody trusts what it represents, it becomes noise.
Avoid these patterns:
- Monitoring the marketing homepage when the repository is for an API.
- Using an endpoint that always returns success while real user flows fail.
- Pointing the badge at a private URL that public readers cannot understand.
- Adding six badges when one status signal would be clearer.
- Hiding the badge below long installation instructions.
The badge should be boring in the best way: small, clear, and backed by a real external check.
When a Live Badge Is Worth Adding
A live uptime badge is especially useful for:
- API clients and SDKs that depend on a public API.
- Open source apps with a hosted demo.
- Documentation sites where availability matters.
- SaaS starter kits with a production sample.
- Internal platform repos shared across teams.
- Agency-maintained client portals where trust and transparency help.
If the repository points readers to a public thing, the README can show whether that public thing is healthy.
Add the Badge With SiteInformant
SiteInformant provides public uptime badges, public status pages, and a clean status API for monitored endpoints.
Start with the public badge workflow here:
Public uptime badges and status pages
Developer-focused monitoring docs are here:
If you want to monitor APIs specifically, including health endpoints and service paths, use:
The end result is a README badge that does not just look nice. It gives visitors a live signal they can act on.
Try SiteInformant: Try It Free