This is only a test site, please use the live site for normal use.

This site is ad-free and I would like to keep it that way. Please consider donating to keep it running. Thanks :)

This page is for developers who wants to integrate the status of Minecraft servers.
If you only need to check the status a server, please go to the main page here.

Minecraft Server Status API

Welcome to the Minecraft Server Status API. This API combines the Ping and Query protocols into one simple JSON output.

Using the API

Use the following endpoint to get the status of a server: https://api.mcsrvstat.us/3/<address>

For Bedrock servers, please use the following endpoint: https://api.mcsrvstat.us/bedrock/3/<address>

The data is returned as application/json and is currently cached for 10 seconds.

If an address works in Minecraft, it works with this API. If you do not specify a port, the API will find it. SRV records are also supported.

Response when server is Online

{
	"online": true,
	"ip": "127.0.0.1",
	"port": 25567,
	"hostname": "server.mymcserver.tld", //Only included when a hostname is detected
	"debug": { //See section below for information about the values
		"ping": true,
		"query": true,
		"srv": true,
		"querymismatch": false,
		"ipinsrv": false,
		"cnameinsrv": false,
		"animatedmotd": false,
		"cachehit": true,
		"cachetime": 1518553220,
		"cacheexpire": 1518553280,
		"apiversion": 2
	},
	"version": "1.12", //Could include multiple versions or additional text
	"protocol": { //Only included when ping is used
		"version": 340,
		"name": "1.12.2" //Only included if a version name is found
	},
	"icon": "data:image\/png;base64,iVBORw0KGgoAAAANSUhEU...dSk6AAAAAElFTkSuQmCC", //Only included when an icon is detected
	"software": "BungeeCord", //Only included when software is detected
	"map": {
		"raw": "MyMcWorld",
		"clean": "MyMcWorld",
		"html": "MyMcWorld"
	},
	"gamemode": "Survival", //Only included for Bedrock servers
	"serverid": "2438134582716697305", //Only included for Bedrock servers
	"eula_blocked": false, //Only included for Java servers
	"motd": {
		"raw": [
			"\u00a7cEver\u00a7r\u00a79PvP \u00a7r\u00a77- \u00a7r\u00a72\u00c9n server, for alle",
			"\u00a7r\u00a7fSe dine stats p\u00e5 \u00a7r\u00a76stats.everpvp.dk\u00a7r"
		],
		"clean": [
			"EverPvP - \u00c9n server, for alle",
			"Se dine stats p\u00e5 stats.everpvp.dk"
		],
		"html": [
			"<span style=\"color: #FF5555\">Ever<\/span><span style=\"color: #5555FF\">PvP <\/span><span style=\"color: #AAAAAA\">- <\/span><span style=\"color: #00AA00\">\u00c9n server, for alle<\/span>",
			"<span style=\"color: #FFFFFF\">Se dine stats p\u00e5 <\/span><span style=\"color: #FFAA00\">stats.everpvp.dk<\/span>"
		]
	},
	"players": {
		"online": 2,
		"max": 100,
		"list": [ //Only included when there are players
			{
				"name": "Spirit55555",
				"uuid": "f6792ad3-cbb4-4596-8296-749ee4158f97"
			},
			{
				"name": "sarsum33",
				"uuid": "d3512599-d4d9-4520-808f-a81f4cdfe8d0"
			}
		],
	},
	"plugins": [ //Only included when plugins are detected
		{
			"name": "WordEdit",
			"version": "6.1.5"
		},
		{
			"name": "WorldGuard",
			"version": "6.2"
		}
	],
	"mods": [ //Only included when mods are detected
		{
			"name": "BiomesOPlenty",
			"version": "2.1.0"
		},
		{
			"name": "MoreFurnaces",
			"version": "1.3.9"
		}
	],
	"info": { //Only included when detecting that the player samples are used for information
		"raw": [
			"\u00a77\u00bb \u00a7cKitPvP \u00a77:: \u00a7f1 \u00a77online",
			"\u00a77\u00bb \u00a7bSurvivalGames \u00a77:: \u00a7f0 \u00a77online"
		],
		"clean": [
			"\u00bb KitPvP :: 1 online",
			"\u00bb SurvivalGames :: 0 online"
		],
		"html": [
			"<span style=\"color: #AAAAAA\">\u00bb <\/span><span style=\"color: #FF5555\">KitPvP <\/span><span style=\"color: #AAAAAA\">:: <\/span><span style=\"color: #FFFFFF\">1 <\/span><span style=\"color: #AAAAAA\">online<\/span>",
			"<span style=\"color: #AAAAAA\">\u00bb <\/span><span style=\"color: #55FFFF\">SurvivalGames <\/span><span style=\"color: #AAAAAA\">:: <\/span><span style=\"color: #FFFFFF\">0 <\/span><span style=\"color: #AAAAAA\">online<\/span>"
		]
	}
}

Response when server is Offline

{
	"online": false,
	"ip": "127.0.0.1", //Could be empty
	"port": 25567, //Could be empty
	"hostname": "not-working.mymcserver.tld", //Only included when a hostname is detected
	"debug": { //See section below for information about the values
		"ping": false,
		"query": false,
		"srv": false,
		"querymismatch": false,
		"ipinsrv": false,
		"cnameinsrv": false,
		"animatedmotd": false,
		"cachehit": false,
		"cachetime": 1518553220,
		"cacheexpire": 1518553280,
		"apiversion": 2
	}
}

Information about debug values

Name	Description
ping	If the Server List Ping (SLP) protocol was used. Added in version 1.7 and can not be turned off.
query	If the Query protocol was used. Default is off.
srv	If a Service record (SRV) was detected and used. They use the following format: `_minecraft._tcp.domain.tld`
querymismatch	If the game port returned by the query protocol is not the same port as the Minecraft server is running on, the API assumes the query comes from another server. You should always set the query port to the same as the Minecraft server.
ipinsrv	If an IP was detected in the SRV record target. SRV record target should only contain A/AAAA records.
cnameinsrv	If a CNAME record was detected in the SRV record target. SRV record target should only contain A/AAAA records.
animatedmotd	If an AnimatedMOTD plugin was detected. This changes the ping response in bad ways. The API will try to compensate, but it might not be correct.
cachehit	If the request was fetched from cache, instead of directly from the server.
cachetime	UNIX timestamp of the time the result was cached.
cacheexpire	UNIX timestamp of the time the cache will expire.
apiversion	The API version used for the request.

Changelog

Only breaking changes will trigger a new version of the API. Other non-breaking changes can happen and will not be noted here.

Version	Changes
3	`players.list` and `players.uuid` has been merged into `players.list` with `name` and `uuid` properties for each player. `map` is now an array with `raw`, `clean` and `html` properties. Note that these properties are strings, not arrays. `plugins` and `mods` have changed to arrays containing `name` and `version` properties for each item. `protocol` is now an array with `version` containing the protocol number and `name` containing the friendly name, if it exists.
2	`offline: true` has been removed from the offline response and replaced with `online: false` `online: true` is now returned when the server is online.
1	Initial version.

HTTP status code endpoint

If you only want to know if a server is online/offline, the HTTP status code endpoint is for you.
This is especially useful if you use some kind of monitoring software that understands HTTP status codes.

Use the following endpoint: https://api.mcsrvstat.us/simple/<address>

For Bedrock servers, use this endpoint: https://api.mcsrvstat.us/bedrock/simple/<address>

Will return 200 OK for online servers and 404 Not Found for offline servers.

Icon endpoint

While the normal endpoint will give you a Base64 version of the server icon, if one is returned by the server, sometimes a direct link to the icon is needed.

Use the following endpoint: https://api.mcsrvstat.us/icon/<address>

A 64x64 PNG image will always be returned. A default Minecraft icon will be returned for servers without an icon and for offline servers.

Problems?

If the API does not give the correct result, or maybe not any result, please first check if the server is working in Minecraft.

If the server is working, try the following debug endpoints for ping and query:

Only use these endpoints for debugging purposes. Use the main API for normal day-to-day use.

https:/api.mcsrvstat.us/debug/ping/<address>
https:/api.mcsrvstat.us/debug/query/<address>
https:/api.mcsrvstat.us/debug/bedrock/<address>

If they give the correct output, you might have found a bug in the API. Please report it via email here: [email protected].