Server Discovery

Overview Authentication Endpoints Rate Limiting Examples
GET /servers/find

Authentication: Optional (Patreon tier unlocks additional features)

Searches for public Minecraft servers with advanced filtering options. Results are paginated and can be sorted by various criteria. Non-Patreon users are limited to 200 results maximum (10 pages × 20 results per page).

Query Parameters

Parameter Type Default Description
version string * Filter by server version. Supports * as wildcard (e.g., 1.20*)
minUsers integer - Minimum number of online players
maxUsers integer - Maximum number of online players
minAge integer - Minimum server age in days (servers last pinged X+ days ago)
maxAge integer 30 Maximum server age in days (servers last pinged within X days)
region string - Filter by region
country string - Filter by country name or code. Supports * wildcard
country_code string - Filter by ISO 3166-1 alpha-2 country code
city string - Filter by city. Auto-wildcarded if not already present
motd string - Filter by server MOTD (Message of the Day). Supports * wildcard
modpack string - Filter by modpack name or short name
org string - Filter by ASN organization name. Supports * wildcard
asn integer - Filter by ASN (Autonomous System Number)
offlineOnly string off Set to any value other than "off" to show only offline mode servers. Non-subscribers limited to 2 pages
noFilter boolean false Set to true to disable TCPShield filter (includes TCPShield proxies)
favicon boolean false Set to true to include server favicon in response
relativeTime boolean false Set to true to format last_ping as relative time (e.g., "2 hours ago")
sort string last_ping Sort results by: users, version, address, port, updated
order string - Sort order (currently not used, sorting handled per-field)
page integer 1 Page number for pagination
limit integer 50 Results per page (max 500 for subscribers, max 20 for non-subscribers)

Example Request

Find all 1.20 servers with 10+ players:

GET /api/v0.1/servers/find?version=1.20*&minUsers=10

Example Response

{
  "displayed": 50,
  "total": 1523,
  "filtered": 892,
  "results": [
    {
      "address": "play.example.com",
      "port": 25565,
      "version": "1.20.1",
      "players_online": 145,
      "players_max": 500,
      "motd": "§6Welcome to Example Server!",
      "motd_stripped": "Welcome to Example Server!",
      "country": "United States",
      "country_code": "US",
      "city": "New York",
      "region": "us-east",
      "asn_number": 16509,
      "asn_name": "Amazon.com Inc.",
      "detected_mod_pack": "All The Mods 9",
      "detected_mod_pack_short": "ATM9",
      "offline_mode": false,
      "last_ping": "2026-01-14T10:30:00Z",
      "favicon": "data:image/png;base64,...",
      "plugins": [
        "EssentialsX",
        "LiteBans",
        "CoreProtect"
      ],
      "players": [
        {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "name": "PlayerName"
        },
        {
          "uuid": "660e8400-e29b-41d4-a716-446655440001",
          "name": "AnotherPlayer"
        }
      ]
    }
  ]
}