Server Status API
A free, keyless REST API for programmatically checking the status of a Minecraft server and getting information on any public Minecraft server in real time. Responses are cached at the edge for 2 minutes. No authentication required, attribution required.
How to Use
- 1Get your server address. This can be a domain name like hypixel.net or an IP with a port like 192.168.1.1:25565. Port is optional and defaults to 25565 for Java or 19132 for Bedrock.
- 2Send a GET request to https://www.minecraftpinger.com/api/v1/<host>:<port> with a User-Agent header identifying your app.
- 3Read the JSON response. If the mc server status is online, the server object contains player count, MOTD, version, ping, and more. If offline, server is null and message is "ok". If message is "upstream_unavailable" we could not check the server rather than finding it down, so retry instead of recording it as offline.
Attribution Required
The API is free to use, including in commercial projects, on one condition: you must credit MinecraftPinger in your public-facing documentation or copy. The credit has to be visible to the people using your project, not buried in a source code comment.
- npm or PyPI package - a line in the README stating that MinecraftPinger provides the server status data, linking to the site.
- Website or hosting provider panel - a line on your homepage, footer, or the page that displays the data, such as "Server status powered by MinecraftPinger".
- Minecraft server site, bot, or app - a credit in your about or help section, or on your credits screen.
Suggested wording
Server status data provided by [MinecraftPinger](https://www.minecraftpinger.com)Failure to attribute may result in your traffic being blocked without notice.
Endpoint
GET https://www.minecraftpinger.com/api/v1/<host>:<port>Port is optional and defaults to 25565 (Java) or 19132 (Bedrock). Both Java Edition and Bedrock Edition servers are supported.
Required Header
User-Agent: your-app/1.0All requests must include a User-Agent header identifying your application. This lets us understand how the API is being used and helps us contact you if something goes wrong. Requests without a User-Agent are rejected with a 400 response.
Code Examples
curl
curl -H "User-Agent: my-app/1.0" https://www.minecraftpinger.com/api/v1/hypixel.netJavaScript (fetch)
const res = await fetch('https://www.minecraftpinger.com/api/v1/hypixel.net', {
headers: { 'User-Agent': 'my-app/1.0' }
})
const data = await res.json()
// data.server is null if the server is offline
console.log(data.server?.players.online)Python
import requests
r = requests.get(
'https://www.minecraftpinger.com/api/v1/hypixel.net',
headers={'User-Agent': 'my-app/1.0'}
)
data = r.json()
# data['server'] is None if the server is offline
print(data['server']['players']['online'])Response
Online server
{
"message": "ok",
"server": {
"ip": "hypixel.net",
"port": 25565,
"players": {
"online": 52847,
"max": 200000
},
"motd": "Hypixel Network [1.8-1.21]",
"version": "Requires MC 1.8 / 1.21",
"ping": 23,
"edition": "java",
"favicon": "data:image/png;base64,..."
}
}Offline or unreachable server
{
"message": "ok",
"server": null
}Status could not be checked (HTTP 200)
{
"message": "upstream_unavailable",
"server": null
}Returned when the Bedrock lookup service we depend on is temporarily limiting us, so we never found out whether the server is up. It is not the same as offline. Still a 200 with the usual shape so existing clients keep working, and it carries a Retry-After header. Retry rather than recording the server as down.
Bedrock not checkable over IPv6 (HTTP 200)
{
"message": "bedrock_ipv6_unsupported",
"server": null
}Returned only for IPv6 addresses. Java Edition is checked in full over IPv6 and did not respond, but our Bedrock status provider accepts only IPv4 addresses and hostnames, so a Bedrock server cannot be ruled out. Query the hostname or IPv4 address to check Bedrock.
Rate limited (HTTP 429)
{
"message": "rate_limited",
"server": null
}rate_limited means your IP reached its limit; target_rate_limited means the requested server reached its limit. Wait for the number of seconds in the Retry-After header before retrying.
| Field | Type | Description |
|---|---|---|
| ip | string | Resolved hostname or IP |
| port | number | Port used |
| players.online | number | Current player count |
| players.max | number | Maximum player slots |
| motd | string | Message of the Day (plain text) |
| version | string | Server version string |
| ping | number | Round-trip latency in milliseconds |
| edition | string | "java" or "bedrock" |
| favicon | string | null | Base64-encoded PNG server icon (Java only) |
Caching
Responses are cached at the CDN edge for 2 minutes. Repeated requests for the same server within that window return the cached result instantly without hitting the origin. You can check the CF-Cache-Status response header to see whether a response was served from cache (HIT) or freshly fetched (MISS).
Frequently Asked Questions
Yes. The API is completely free. No account, credit card, or API key is required. There is one condition: you must credit MinecraftPinger in your public-facing documentation or copy. Send a GET request with a User-Agent header and you will receive the mc server status instantly.
No API key is required. The only technical requirement is a User-Agent header that identifies your application. This helps us understand usage patterns and reach out if anything looks wrong. Separately, attribution to MinecraftPinger is required in any public-facing documentation or copy.
Yes, attribution is mandatory. Any public-facing documentation or copy, such as an npm package README, a website homepage or footer, a hosting provider panel, or a bot about command, must state that MinecraftPinger provides the server status data and link to https://www.minecraftpinger.com. Projects that use the API without attributing it may be blocked without notice.
An IP address that sends more than 10 uncached requests in 10 minutes is blocked for 10 minutes. A server hostname that receives more than 720 uncached requests in 24 hours is blocked for 24 hours. Ports are ignored for the server limit, while subdomains are counted separately. A blocked request returns HTTP 429 with a Retry-After header.
Yes. The API automatically detects whether a server is Java or Bedrock Edition and uses the correct protocol. Bedrock servers typically run on port 19132. You can also check Java Edition servers on port 25565 (the default). One limitation: Bedrock status cannot be checked over IPv6, so an IPv6 address returns message "bedrock_ipv6_unsupported" when Java does not answer. Java Edition works fully over IPv6.
A null server field means we have no status to give you, and the message field says why. With message "ok" the server is offline or unreachable: it is down, the address is wrong, or a firewall is blocking the connection. With message "upstream_unavailable" the server may well be fine and we simply could not check it, because the Bedrock lookup service we rely on was temporarily limiting us; retry after a minute rather than recording the server as down. With message "bedrock_ipv6_unsupported" the address is IPv6: Java Edition was checked in full and did not answer, but Bedrock cannot be checked over IPv6, so query the hostname or IPv4 address instead. An online server returns a full object with player count, MOTD, version, and more.
Yes. Because responses are cached at the edge for 2 minutes, polling every few minutes is efficient and will not overload the origin. The CF-Cache-Status response header tells you whether the result came from cache (HIT) or was freshly fetched (MISS).
Built by MinecraftPinger.com