Guide
How to Add an Uptime Badge to Your GitHub README
Most GitHub READMEs show build status and test coverage. But what about uptime? If your project exposes an API or website, an uptime badge tells contributors and users that your service is live and healthy — right at the top of the page.
This guide shows you how to add real-time uptime, status, and response time badges to any GitHub README using UptimeSignal. It takes under a minute and costs nothing.
What it looks like in a README:
Step 1: Create a monitor
Sign up for a free UptimeSignal account and add your endpoint as a monitor. Enter the URL, give it a name, and save. Public badges are enabled by default — no extra configuration needed.
The free plan includes 25 monitors with 5-minute check intervals, which is enough for most open-source projects.
Step 2: Copy the badge Markdown
Open your monitor in the dashboard and click the Badge button. Select the badge type you want (uptime, status, or response time) and copy the Markdown.
Or use these templates directly — just replace YOUR_MONITOR_ID with the ID from your monitor's badge URL:
Uptime percentage (30 days)
[](https://uptimesignal.io/badges)
Current status
[](https://uptimesignal.io/badges)
Response time (24h average)
[](https://uptimesignal.io/badges)
"Monitored by UptimeSignal" (no monitor needed)
This branding badge doesn't require a monitor ID — you can use it immediately:
[](https://uptimesignal.io/badges)
Step 3: Paste into your README.md
Add the Markdown to the top of your README.md, usually right after the project title. Here's what a typical README header looks like:
# My API
[](https://github.com/user/repo/actions)
[](https://uptimesignal.io/badges)
[](https://uptimesignal.io/badges)
A fast, reliable API for...
Commit and push. The badges appear immediately and update automatically.
How it works
UptimeSignal checks your endpoint on a schedule (every 5 minutes on Free, every 1 minute on Pro). The badge SVG is served from api.uptimesignal.io and cached for 5 minutes. GitHub fetches and caches the SVG through its image proxy (camo.githubusercontent.com), so visitors see updated data without hitting the API directly.
Badge colors
| Badge | Green | Yellow | Red |
|---|---|---|---|
| Uptime | ≥99% | 95–99% | <95% |
| Status | Operational | Pending | Down |
| Response | <500ms | 500–1000ms | >1000ms |
Works beyond GitHub
The same Markdown works on GitLab, Bitbucket, and any platform that renders Markdown images. For documentation sites (Docusaurus, GitBook, ReadTheDocs) and regular websites, use the HTML embed:
<a href="https://uptimesignal.io/badges"><img src="https://api.uptimesignal.io/badge/YOUR_MONITOR_ID/uptime.svg" alt="Uptime"></a>
For Notion, paste the direct image URL (https://api.uptimesignal.io/badge/YOUR_MONITOR_ID/uptime.svg) as an embed block.
Privacy and control
Badges never expose your endpoint URL. They only show the metric (uptime %, status, or response time). If you want to disable a badge for a specific monitor, toggle off "Public Badge" in the monitor's advanced settings.
Programmatic access
Need badge data in JSON? Use the data endpoint:
curl https://api.uptimesignal.io/badge/YOUR_MONITOR_ID/data.json
Returns uptime percentage, current status, and average response time. Useful for building custom dashboards or status widgets.
Get your uptime badge
Free account. 25 monitors. Badges enabled by default.
Start monitoring free →Or learn more about all badge types.