Server Status API

How to Use

1. 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.
2. 2Send a GET request to https://minecraftpinger.com/api/v1/<host>:<port> with a User-Agent header identifying your app.
3. 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.

Endpoint

GET https://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.0

All 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://minecraftpinger.com/api/v1/hypixel.net

JavaScript (fetch)

const res = await fetch('https://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://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
}

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