Integrate monitoring data into your workflows and display uptime on your website. This guide covers the Socket.IO API, API keys, common operations, Prometheus metrics for Grafana, and how to embed status badges on your UK WordPress site or shop.
Understanding the Uptime Kuma API • Generating and using API keys • Common API operations • Prometheus metrics for Grafana • What are status badges • Badge types and URLs • Customising and embedding badges • FAQ
Uptime Kuma provides an API that lets you retrieve monitoring data, manage monitors programmatically and integrate uptime information with external tools. Display live uptime on your WordPress site, feed data into Grafana, automate monitor creation from deployment scripts.
Important: the primary API uses Socket.IO, not traditional REST. Socket.IO is a real-time bidirectional protocol — the same technology that powers the web dashboard. Client libraries exist for Python (uptime-kuma-api) and Node.js (socket.io-client). Read-only endpoints like badges and Prometheus metrics are accessible via standard HTTP GET.
Authorization: Bearer YOUR_API_KEY header. For Socket.IO, use loginByToken event.Tip: create separate keys per integration. If one key is compromised, revoke without affecting others. Set expiry on temporary-use keys.
Through the Socket.IO API, most web interface operations are available:
monitorList event after authheartbeat event fires on every checkaddMonitor with configurationeditMonitor, deleteMonitorpauseMonitor, resumeMonitor for deployment windowstestNotification verifies channelsThe Python uptime-kuma-api library wraps these events in a clean Pythonic interface.
Uptime Kuma exposes monitoring data as Prometheus metrics at /metrics:
monitor_response_time — response time per monitor in msmonitor_status — current status (1=up, 0=down)monitor_cert_days_remaining — days until SSL expirymonitor_cert_is_valid — certificate currently valid (boolean)Add the /metrics URL as a Prometheus data source in Grafana. Build custom dashboards combining uptime with other metrics (server load, database, application logs).
Status badges are embeddable SVG images showing real-time information about monitors — the same kind you see on GitHub showing build status or uptime percentage. Uptime Kuma generates badges showing whether a service is up/down, uptime percentage, or average response time.
Badges are publicly accessible by default (no auth required), ideal for public-facing pages, documentation and READMEs.
Replace :id with your monitor ID (visible in dashboard URL when viewing a monitor).
| Badge type | URL pattern | Shows |
|---|---|---|
| Status | /api/badge/:id/status | UP or DOWN |
| Uptime (24h) | /api/badge/:id/uptime/24 | e.g. 99.9% |
| Uptime (30d) | /api/badge/:id/uptime/720 | e.g. 99.95% |
| Response time (24h) | /api/badge/:id/ping/24 | e.g. 245 ms |
| Certificate expiry | /api/badge/:id/cert-exp | e.g. 29 days |
Customise appearance via query parameters:
?label=My+Website — override label text?labelColor=555 — label background (hex, no #)?upColor=2563eb — up state colour?downColor=dc2626 — down state colour?style=flat-square — badge style: flat, flat-square, for-the-badge, plastic, socialExample: https://your-instance.uptimekuma.io/api/badge/1/status?label=Homepage&style=flat-square&upColor=16a34a
Use a standard <img src="BADGE_URL" /> tag. Works in WordPress footer widgets, documentation pages, email signatures.
.../api/badge/1/status?label=Site+Status&style=flat-square<img> tag.Tip: combine multiple badges for a professional look — status, uptime percentage and response time side by side. Gives visitors confidence that you actively monitor your services.
Monitor + display badges for £1/month
SmartXHosting Uptime Kuma Hosting gives you unlimited monitors, badge URLs, API access and Prometheus metrics — UK-hosted, managed, from £1/month.
View Uptime Kuma HostingQ: Does Uptime Kuma have a REST API?
A: Primarily Socket.IO. Read-only endpoints (badges, Prometheus metrics) accessible via standard HTTP GET.
Q: How do I get an API key?
A: Settings › API Keys › Add API Key. Name, optional expiry, copy once. Use as Bearer TOKEN in Authorization header.
Q: How do I embed a status badge on my site?
A: Find monitor ID in dashboard URL. Use <img src="https://your-instance.uptimekuma.io/api/badge/ID/status">. Add to WordPress via Custom HTML widget or directly to theme.
Q: Can I connect to Grafana?
A: Yes. Enable Prometheus metrics, add /metrics as Prometheus data source in Grafana, build custom dashboards.
Q: Which programming languages work with the API?
A: Any with a Socket.IO client library. Python (uptime-kuma-api), Node.js (socket.io-client). REST badge/metrics endpoints work from any HTTP-capable language.
Q: Are badges cached?
A: Yes — edge CDN caching for performance. Status changes may take a minute to reflect in badge displays.