Status Badges

Put a live uptime, status or response-time badge in your README — one switch, one copy-paste.

What is a status badge?

A status badge is a small SVG image Enori generates on demand for one of your monitors. You embed its URL anywhere an image works — a GitHub README, a docs site, an internal wiki, a marketing page — and it stays current on its own — Enori renders it on request, so you never edit the number by hand. (It can be up to five minutes behind; see Caching.)

Three badges, one per monitor:

(The left half of a badge is its label, the right half its value.)

They look like the badges you already have in that README — same shields.io house style, same four style variants — so a row of badges stays visually consistent.

When to use it

• An open-source project's README. "Is the demo API actually up?" answered without anyone opening a

dashboard.

• A public docs or developer portal page for an API your customers integrate against.
• A team wiki or internal homepage where a full status page would be more than you need.
• A vendor page or a proposal where you want the uptime claim to be checkable rather than asserted.

When a status page is the better tool: if you want to show several monitors together, publish incident history, let people subscribe to updates, or brand the page — that's a status page, not a badge. A badge is one monitor, one number.

Badges are off by default

Nothing is published until you switch it on, per monitor. Until you do, every badge URL for that monitor renders a grey unknown image. That is deliberate: a badge URL is public and unauthenticated, so publishing has to be a choice you make, not a default you inherit.

Turn one on

1. Open the monitor (Monitors → click it). The Status badges panel is at the bottom of the

page, collapsed, with an Off pill next to it.

1. Expand it and flip Serve public badges on. The pill changes to Public.
2. Pick the badge, period, label and style you want. The preview updates as you type.
3. Copy the Markdown or HTML snippet and paste it wherever you want the badge.

The panel is on every monitor type — Website, Browser, API Flow, Ping, Port, DNS, Domain and Cron Job all have it.

What switching it on actually publishes

While badges are on for a monitor, anyone who has the badge URL can read that monitor's uptime percentage, current status and average response time without signing in. That is what makes a badge work in a public README.

Nothing else is exposed. The badge image contains a label, one value, a colour and an accessible title built from those two strings — and that is all. Not the monitored URL, not the monitor's name, not its check history, not your tags, not your other monitors, not your account. Someone who finds a badge URL learns exactly the one figure you chose to publish.

Badge URLs are not guessable either: a monitor id is mon_ followed by 32 hexadecimal characters, generated randomly when the monitor is created. And a badge URL for a monitor that has not been switched on returns exactly the same grey image as a badge URL for a monitor that does not exist — so the endpoint cannot be used to find out which monitors you have.

Turning it off — and the five-minute tail

Flip the switch back off and Enori stops serving the real badge immediately: the very next request gets the grey unknown image. The publication check is never cached.

But the image already delivered can keep showing for up to about five minutes. Every badge response carries Cache-Control: public, max-age=300, so a reader's browser, a docs CDN, or GitHub's image proxy may serve the copy it already has until that expires. If you switch a badge off and someone tells you it is still showing, that is what is happening — wait five minutes and hard-refresh.

There is nothing you can do to shorten that tail — not deleting the monitor, not changing the URL — because the copy lives in caches you do not control. Plan for it: switch off a few minutes before you need the badge to be gone.

The URL

https://api.enori.io/api/badges/{monitorId}/uptime.svg
https://api.enori.io/api/badges/{monitorId}/status.svg
https://api.enori.io/api/badges/{monitorId}/response-time.svg

The Status badges panel fills in the monitor id for you. If you are writing the URL by hand, copy the id from that panel rather than retyping it.

Parameters

period and style are case-insensitive, so ?period=24H and ?style=Flat work.

Pick a badge in the panel

The builder offers all three badges and all four styles, so you never need to edit a URL by hand. Choose the badge, the window and the style, type a label if you want one, and copy the Markdown or HTML — the preview above the snippet is the exact image your readers will get.

Period is only offered where it means something. The uptime and response-time badges both summarise a window, so the picker is live for those two. The status badge reports where the monitor is right now, so the picker greys out — there is no window to choose.

Embedding

Markdown

[![Uptime](https://api.enori.io/api/badges/mon_abc123/uptime.svg)](https://app.enori.io/dashboard/monitors/mon_abc123)
[![Status](https://api.enori.io/api/badges/mon_abc123/status.svg?style=flat-square)](https://app.enori.io/dashboard/monitors/mon_abc123)

HTML

<a href="https://app.enori.io/dashboard/monitors/mon_abc123">
  <img src="https://api.enori.io/api/badges/mon_abc123/uptime.svg" alt="Uptime" />
</a>

The panel gives you the linked form, because it costs nothing extra to paste and a reader who sees a red badge can click through instead of screenshotting it at you. A bare !Uptime works too if you prefer.

Note on the link target. The link goes to the monitor's page in your dashboard, which requires signing in — so a public reader who clicks it lands on the Enori sign-in page. That is fine for a team README, less so for a fully public one. If you want a clickable destination the public can actually read, point the link at a status page instead and keep the badge image as-is.

What the badge says

Uptime

The percentage of checks that passed over the window, to two decimals — 99.87%. It is the same number the monitor's detail page shows for the same range: settled results only (a blip that was immediately re-verified and cleared does not count against you), and time inside a declared maintenance window is excluded from both sides of the ratio.

The colour is a five-band scale:

Status

One word for what the monitor is doing right now:

A paused monitor still serves its badges if you left them switched on — the status badge says paused and the uptime badge keeps reporting the window it can measure. Pausing a monitor does not unpublish it; the Serve public badges switch does.

Response time

The average response time over the window, in whole milliseconds — 183 ms. Same population as the uptime badge and as the monitor's detail page: successful checks only, with a measured response time, outside maintenance.

It is always blue, on purpose. Unlike uptime, where 99.9% means the same thing to everybody, a "good" response time depends entirely on what you are measuring — 800 ms is fine for a report endpoint and terrible for a CDN edge. Colouring it would publish a verdict you never configured, on your own README. The number speaks for itself.

Domain and Cron Job monitors have no response time, so their response-time badge always reads no data. Neither type makes a timed network request of its own — a Domain check reads stored registry data, and a Cron Job monitor waits for your job to ping us — so there is nothing to average. This is the same reason Enori will not let you create a latency SLO on those two types. Use the uptime or status badge for them.

Labels

Anything you type in Label replaces the left-hand caption. Characters outside letters, digits, spaces, -, _ and . are silently removed — the badge still renders, just without them — and the result is cut to 30 characters.

Letters and digits from any alphabet survive, so café, приложение and 日本 come through intact. Punctuation and symbols do not:

The removal happens first and the 30-character cut afterwards. If nothing usable survives, the badge falls back to that endpoint's own default word — uptime, status or response. The panel shows you the cleaned-up result as you type, so you never have to guess.

Caching

Badges are cached for five minutes, in two places:

• On our side, the uptime and response-time figures are computed at most once every five minutes

per monitor and window, so a badge in a busy README does not run a database aggregation per page view.

• On the reader's side, the response says max-age=300, so browsers and image proxies hold their

copy for up to five minutes.

The practical consequence: a badge can be up to about five minutes behind reality. That is the right trade for a README, and it is also why switching badges off has the five-minute tail described above. The publication switch itself is not cached — only the numbers are.

Badge requests are rate-limited to 60 per minute per IP address. A badge in a README does not come close to that: image proxies and browsers cache the response, so your readers do not each generate a request.

Troubleshooting

Why is my badge grey?

A grey badge is one of two words, and they mean different things.

Grey unknown — one of these, in the order worth checking:

1. Badges are not switched on for that monitor. By far the most common cause. Open the monitor →

Status badges → check the pill reads Public, not Off.

1. The monitor id is wrong, or the monitor was deleted. Ids are mon_ plus 32 hexadecimal

characters; copy it from the panel rather than retyping it.

1. You switched it off in the last five minutes — see the cache tail.
2. On the status badge only: the monitor genuinely has no verdict yet — it has never completed a

check, or the last check could not be classified.

These are deliberately indistinguishable from each other on the wire, so nobody can use a badge URL to work out which monitor ids exist. That means the badge cannot tell you which one it is — check the panel.

Grey no data — not an error. The monitor is switched on and running, but the window you asked for contains nothing to measure: a brand-new monitor, or a window whose every check fell inside a maintenance window. Widen period, or wait for the next check. On the response-time badge it is also permanent for Domain and Cron Job monitors, which record no response time at all — see Response time.

The badge says invalid period

You sent a period value that is not one of 24h, 7d, 30d, 90d. Enori refuses it visibly rather than quietly substituting 30 days — because period changes the number you are publishing, and a silently wrong number on a public README is worse than a visible complaint. Fix the parameter and the badge renders normally. (Note that 30 and 1y are both invalid; 24H is fine.)

The badge does not match my dashboard

Two things to check before assuming a bug:

• The five-minute cache. Hard-refresh, or wait it out.
• The window. The badge defaults to 30d; if your dashboard is showing 24 hours, those are

different questions with different answers.

Beyond that they should agree exactly — the badge is computed from the same settled, maintenance-excluded population as the monitor detail page, on purpose.

My style choice did nothing

An unrecognised style falls back to flat rather than erroring, since the only thing at stake is how the corners look. Check the spelling: flat, flat-square, plastic, for-the-badge (with hyphens).

Half my label disappeared

See Labels — the whitelist strips punctuation and symbols. The panel previews the cleaned result as you type.

The badge is not showing in my README at all

• GitHub proxies images. A freshly published badge can take a moment to appear, and GitHub's proxy

has its own cache on top of ours.

• Check the URL is the API host, https://api.enori.io/..., not the app host.
• Open the URL directly in a browser. If you see a badge there, the problem is in the embed; if you

see a grey one, work through Why is my badge grey?.

Using Shields.io instead

If you already use Shields.io and want a badge in its exact house style, point its dynamic/json badge at a public status page's uptime history, which is plain JSON and needs no API key:

https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.enori.io%2Fapi%2Fstatus-pages%2Fpublic%2FYOUR-SLUG%2Fuptime-history&query=%24.overallUptimePct&label=uptime

Use overallUptimePct — it is uptime across every monitor on the page, weighted by check count. The per-day entries in days carry a placeholder of 100 for days with no recorded checks (flagged hasData: false), so a badge built on a single day can show a perfect score for a day nobody watched. overallUptimePct is null when the whole window has no checks.

The status page must be public and not password-protected. There is no per-monitor JSON endpoint — a monitor is published either through its own badge switch or through a status page, and both are choices you make deliberately.

Related documentation

• API reference — the same endpoints from the API user's angle, including switching

badgesEnabled from POST/PUT /api/monitors and from the MCP server.

• Maintenance windows — why maintenance downtime does not appear in the number

the badge publishes.

• Uptime reports — a full SLA document when a badge is not enough.
• SLOs — continuous reliability tracking with alerting, rather than a published figure.

Last updated: 2026-08-22. Feedback or corrections: support@enori.io