API documentation

Free JSON API over the same measured data the site runs on — every number comes from a real ping, never an estimate. No key required to start; keys raise your rate limits.

Authentication & rate limits

Anonymous requests share a per-IP budget of 120/min (with no daily cap) on the status and listing endpoints. Pass an API key to get your own dedicated, higher budget:

curl -H "Authorization: Bearer mcs_live_…" \
  "https://mc-servers.io/api/servers?sort=players"

Tier	Per minute	Per day	How to get it
Free key	180	5,000	Create one in your dashboard (free account)
Premium key	600	50,000	Own at least one Premium server when creating the key

GET/api/tools/status?address={host[:port]}key raises limits

Live status check for any Minecraft server (listed or not): online state, players, version, MOTD, favicon.

address — host or host:port (Java default 25565)

curl "https://mc-servers.io/api/tools/status?address=mc.hypixel.net"

GET/api/servers?{sort,category,edition,search,page,limit}key raises limits

The public directory: filterable, paginated listing with cached live metrics (refreshed every 5 minutes).

sort — votes | players | uptime | newest
edition — JAVA | BEDROCK | CROSSPLAY
category — category slug (e.g. skyblock)
q — search — matches name, IP, description
page / limit — pagination (limit ≤ 100)

curl "https://mc-servers.io/api/servers?sort=players&limit=10"

GET/api/servers/{slug}

One listed server's public profile and cached live metrics. Cached ~30s.

slug — from the server's public page URL

curl "https://mc-servers.io/api/servers/hypixel"

GET/api/servers/{slug}/uptime?days={7-90}

Daily uptime history (percent, peak players). Free servers cap at 30 days; Premium servers expose up to 90.

days — 7–30 (free) or 7–90 (premium server)

curl "https://mc-servers.io/api/servers/hypixel/uptime?days=30"

GET/api/servers/{slug}/player-trend?range={24h|7d|30d|90d}

Player-count trend from 5-minute snapshots (24h/7d) or daily aggregates (30d/90d). Ranges beyond 24h require the server to be Premium.

range — 24h (free) · 7d/30d/90d (premium server)

curl "https://mc-servers.io/api/servers/hypixel/player-trend?range=24h"

GET/api/banner/{address}?style={dark|light|minimal|minecraft}

Embeddable live-status SVG badge (468×60). Free badges carry a small mc-servers.io mark; Premium servers get a clean badge.

style — badge theme, default dark

<img src="https://mc-servers.io/api/banner/mc.hypixel.net?style=dark" alt="Server status" />

About the data

Listed servers are pinged every 5 minutes; on-demand checks run live at request time. Fields we can't measure are null — never a guess. Player counts are clamped against implausible self-reported values. Uptime history is aggregated daily and kept for 90 days; raw pings are kept for 7.

Get an API key