How to Use Uptime Badges in Your GitHub README

Open source projects and public APIs often display status badges in their README — build passing, coverage percentage, latest version. An uptime badge adds one more signal: "this service is running." It's a trust indicator that requires no maintenance once set up.

Step 1: Find your badge URL

Each PingBase monitor has a unique badge URL. To find it:

1. Log into app.pingba.se
2. Open a monitor
3. Click Badge in the monitor detail view
4. Copy the badge URL or the ready-to-use Markdown snippet

The badge URL format is:

https://app.pingba.se/badge/YOUR_MONITOR_ID

This returns a live SVG image. Every time it's loaded, it reflects the current uptime percentage for that monitor over the last 30 days.

Step 2: Add to your GitHub README

In Markdown, embed an image with a link:

[![Uptime](https://app.pingba.se/badge/YOUR_MONITOR_ID)](https://pingba.se/status/YOUR_STATUS_PAGE_SLUG)

This renders as a clickable badge — clicking it takes users to your public status page where they can see uptime history and any active incidents.

The badge displays as:

(example — your badge will show real data)

Badge styles

PingBase badges adapt their color automatically based on your current uptime:

Embedding in HTML (websites, docs)

For HTML pages — your docs site, landing page, or product website — use an <img> tag wrapped in a link:

<a href="https://pingba.se/status/YOUR_SLUG">
  <img src="https://app.pingba.se/badge/YOUR_MONITOR_ID"
       alt="Uptime status"
       height="20" />
</a>

For Next.js or React, use the <img> directly or Next's Image component with unoptimized to preserve the live SVG:

import Image from 'next/image';

<a href="https://pingba.se/status/YOUR_SLUG">
  <Image
    src="https://app.pingba.se/badge/YOUR_MONITOR_ID"
    alt="Uptime"
    width={100}
    height={20}
    unoptimized
  />
</a>

Multiple monitors, one README section

If you have multiple components to display — API, dashboard, webhooks — you can show several badges in a row:

## Status

[![API](https://app.pingba.se/badge/MONITOR_ID_API)](https://pingba.se/status/your-slug)
[![Dashboard](https://app.pingba.se/badge/MONITOR_ID_DASH)](https://pingba.se/status/your-slug)
[![Webhooks](https://app.pingba.se/badge/MONITOR_ID_WH)](https://pingba.se/status/your-slug)

This renders as a row of badges, each labeled with the monitor name, each linking to your status page. Users can see at a glance which components are healthy.

Caching behaviour

Badge SVGs from PingBase are served with short cache headers — they refresh within a few minutes of a status change. GitHub's CDN caches badge images for a few minutes on their end as well, which is normal behaviour for all badge providers (including Shields.io).

This means: if your service goes down, the badge will reflect that within a few minutes. It's not real-time to the second, but it's accurate enough for the purpose — giving README readers a current sense of your service's health.

Good places to put uptime badges

• GitHub README — top section, near build/test status badges
• Documentation site — in the header or a "Service status" section
• Landing page — near the pricing section or in the footer
• API reference docs — next to the base URL, showing API availability
• Developer portal — on the dashboard or home page

The badge works best when it's linked to your full status page. That way, curious users who click it see the full uptime history and any active incidents — not just a number.