Badges
Embed a site's uptime or current status as an SVG image: both endpoints, their parameters, colors and embed snippets.
Last reviewed
On this page
A badge is a small SVG image that shows a site's uptime or current status. Put it in a README, a documentation page or your own website. The image is generated each time it's requested, so it follows the site.
Get the embed code
Open a site and find the Badge & Embed card on its detail page. It previews each badge and gives a Markdown snippet, an HTML snippet and a direct URL to copy. The uptime badge has 7d, 30d and 90d buttons that set its time window. The id in the address is the site's id, and it's the only thing that selects the site.
Uptime badge
GEThttps://octoping.com/api/badges/{webpage_id}.svg
Uptime Badge
webpage_id(path, string, required)label(query, string, optional, defaultuptime)days(query, integer, optional, default30)
| Parameter | Default | Behavior |
|---|---|---|
label | uptime | The text on the left of the badge. |
days | 30 | The number of days to measure. Values below 1 are raised to 1 and values above 90 are lowered to 90. |
The value is the site's uptime percentage over the window, rounded to two decimals. It's the same calculation as the uptime figure in the app, so maintenance time is left out and checks from every vantage point count. The uptime and outages page explains it. When the window holds no counted checks, the badge reads N/A.
The color of the value follows the percentage.
| Uptime | Color |
|---|---|
| 99.9% or more | Green |
| 99% to under 99.9% | Light green |
| 95% to under 99% | Orange |
| Under 95% | Red |
| N/A | Gray |
Status badge
GEThttps://octoping.com/api/badges/{webpage_id}/status.svg
Status Badge
webpage_id(path, string, required)label(query, string, optional, defaultstatus)
| Parameter | Default | Behavior |
|---|---|---|
label | status | The text on the left of the badge. |
The value is the site's current status in the public vocabulary, the same one a status page uses. The statuses are on the statuses page.
| Value | Public status | Shown for |
|---|---|---|
| up | Operational | Online and Partial |
| degraded | Degraded | Degraded |
| down | Down | Offline |
| maintenance | Under maintenance | Maintenance |
| unknown | Unknown | Pending, and any site whose workspace has monitoring paused |
Up is green, degraded is orange, down is red, maintenance is blue and unknown is gray.
Unknown sites
A site id that doesn't exist, or a site that's switched off, returns HTTP 404 with a gray badge that reads not found. The image still renders, so a stale embed shows a clear message instead of a broken picture.
Response headers
A badge that renders with HTTP 200 carries these headers.
- Content type:
image/svg+xml - Cache control:
no-cache, max-age=300 - CORS:
Access-Control-Allow-Origin: *, so any page can load the image.
Embedding
Markdown:
HTML:
<img src="https://octoping.com/api/badges/YOUR_SITE_ID.svg" alt="Uptime" />
<img src="https://octoping.com/api/badges/YOUR_SITE_ID/status.svg" alt="Status" />A longer window and a custom label:
https://octoping.com/api/badges/YOUR_SITE_ID.svg?days=90&label=90-day%20uptimeRelated
- DocsAPI overviewThe public endpoints OctoPing offers today, how they are authenticated, their limits and what is not available yet.
- DocsUptime, downtime and outagesHow uptime percentage, downtime and outage counts are computed, why they don't add up to each other and how maintenance and probe results change them.
- DocsStatusesThe statuses a site and a heartbeat can have in the app and on a public status page, and the order in which the rules apply.
- FeatureWhite-label status pages with custom domains and subscribersPublish a status page in your client's branding, with incidents, scheduled maintenance, email subscribers, feeds and client contacts. Custom domains on paid plans.
- GuideAdd an uptime badge to a README, report or footerShow a site's live uptime or current status as a small image in a README, a client report or a website footer.