API Documentation

API Documentation — Log in to manage keys and use the API.
API Documentation

Every request must be authenticated with an API key. You have two options:

HTTP Header (recommended)
Authorization: Bearer qg___your_key_here
Query Parameter
?api_key=qg__your_key_here

Dein Account darf maximal 5.000 Anfragen pro Tag stellen – unabhängig davon, wie viele Keys du verwendest. Der Zähler wird täglich um 00:00 UTC zurückgesetzt. Das verbleibende Kontingent ist in den Antwort-Headern enthalten:

Your account may make at most 5,000 requests per day — regardless of how many keys you use. The counter resets daily at 00:00 UTC. Remaining quota is returned in response headers:

Tu cuenta puede realizar un máximo de 5.000 solicitudes por día, independientemente de cuántas claves utilices. El contador se reinicia diariamente a las 00:00 UTC. El cupo restante se incluye en los headers de respuesta:

Your account may make at most 5,000 requests per day — regardless of how many keys you use. The counter resets daily at 00:00 UTC. Remaining quota is returned in response headers:

Your account may make at most 5,000 requests per day — regardless of how many keys you use. The counter resets daily at 00:00 UTC. Remaining quota is returned in response headers:

Ваш аккаунт может выполнять не более 5,000 запросов в день — независимо от количества используемых ключей. Счётчик сбрасывается ежедневно в 00:00 UTC. Оставшаяся квота возвращается в заголовках ответа:

Hesabınız günde en fazla 5,000 istek yapabilir — kaç anahtar kullandığınızdan bağımsız. Sayaç her gün 00:00 UTC'de sıfırlanır. Kalan kota yanıt başlıklarında yer alır:

您的账户每天最多可发出 5,000 个请求——无论使用多少个密钥。计数器每天 00:00 UTC 重置。剩余配额在响应头中返回： 

X-RateLimit-Limit: 5000X-RateLimit-Remaining: 874
X-RateLimit-Reset: 2024-12-01

HTTP status codes:

200 OK – Request successful
400 Bad Request – Missing or invalid parameters
401 Unauthorized – Key missing or invalid
404 Not Found – Server ID does not exist
429 Too Many Requests – Rate limit reached
503 Service Unavailable – API disabled

The game parameter accepts the following slugs:

Slug Game App ID Example URL
arksa ARK: Survival Ascended 2399830 /api/v1/servers?game=arksa&limit=10
arkse ARK: Survival Evolved 346110 /api/v1/servers?game=arkse&limit=10
arma3 ArmA 3 107410 /api/v1/servers?game=arma3&limit=10
atlas Atlas 834910 /api/v1/servers?game=atlas&limit=10
ats American Truck Simulator 270880 /api/v1/servers?game=ats&limit=10
barotrauma Barotrauma 602960 /api/v1/servers?game=barotrauma&limit=10
beamng BeamNG.drive 284160 /api/v1/servers?game=beamng&limit=10
empyrion Empyrion - Galactic Survival 383120 /api/v1/servers?game=empyrion&limit=10
ets2 Euro Truck Simulator 2 227300 /api/v1/servers?game=ets2&limit=10
garrysmod Garry's Mod 4000 /api/v1/servers?game=garrysmod&limit=10
groundbranch GROUND BRANCH 16900 /api/v1/servers?game=groundbranch&limit=10
hellletloose Hell Let Loose 686810 /api/v1/servers?game=hellletloose&limit=10
icarus ICARUS 1149460 /api/v1/servers?game=icarus&limit=10
insurgency Insurgency 222880 /api/v1/servers?game=insurgency&limit=10
killingfloor2 Killing Floor 2 232090 /api/v1/servers?game=killingfloor2&limit=10
minecraftbedrock Minecraft (Bedrock) 0 /api/v1/servers?game=minecraftbedrock&limit=10
minecraftjava Minecraft (Java) 0 /api/v1/servers?game=minecraftjava&limit=10
nmrih No More Room in Hell 224260 /api/v1/servers?game=nmrih&limit=10
rs2vietnam Rising Storm 2: Vietnam 418460 /api/v1/servers?game=rs2vietnam&limit=10
sbox s&box 590830 /api/v1/servers?game=sbox&limit=10
scum SCUM 513710 /api/v1/servers?game=scum&limit=10
sonsoftheforest Sons Of The Forest 1326470 /api/v1/servers?game=sonsoftheforest&limit=10
spaceengineers Space Engineers 244850 /api/v1/servers?game=spaceengineers&limit=10
stormworks Stormworks: Build and Rescue 573090 /api/v1/servers?game=stormworks&limit=10
theforest The Forest 242760 /api/v1/servers?game=theforest&limit=10
truckersmp TruckersMP 0 /api/v1/servers?game=truckersmp&limit=10
unturned Unturned 304930 /api/v1/servers?game=unturned&limit=10
vrising V Rising 1604030 /api/v1/servers?game=vrising&limit=10
Endpoints
Returns a list of game servers sorted by player count.

count is the number of servers in this response (length of servers). It never exceeds limit; on the last page it may be smaller.

Parameter Type Required Default Description
game string Yes – Which configured server list to query: the game parameter must match the slug of an enabled game in this install (lowercase letters, digits, hyphen).
limit integer No 100 Number of results (max: 10,000)
offset integer No 0 Pagination offset
sort string No players Sort field: players, max_players, name, version, rank, fetched_at, first_seen_at, days, country.
order string No desc Sort direction: desc or asc.
online integer No – 1 = online only, 0 = offline only
password integer No – 1 = password-protected only, 0 = no-password only.
official integer No – 1 = official servers only, 0 = unofficial only.
has_owner integer No – 1 = only verified-claimed servers, 0 = unowned only.
country string No – One or more ISO 3166-1 alpha-2 codes, comma-separated (e.g. DE,US,GB).
ip_prefix string No – IP prefix for range match (e.g. 192.168. matches all servers in 192.168.0.0/16).
search string No – Free-text search in server name and IP (substring)
map string No – Substring match on map name (case-insensitive).
gamemode string No – Substring match on gamemode.
version string No – Substring match on game version.
players_min integer No – Minimum current player count.
players_max integer No – Maximum current player count.
max_players_min integer No – Minimum slot capacity.
max_players_max integer No – Maximum slot capacity.
days_min integer No – Minimum days since server start.
days_max integer No – Maximum days since server start.
rank_min integer No – Minimum rank.
rank_max integer No – Maximum rank.
fetched_after integer No – Only servers last fetched after this Unix timestamp.
fetched_before integer No – Only servers last fetched before this Unix timestamp.
first_seen_after integer No – Only servers first recorded after this Unix timestamp.
first_seen_before integer No – Only servers first recorded before this Unix timestamp.
Response fields
Field Type Description
game string Slug of the game (e.g. arkse, conanexiles).
game_label string Display name of the game.
app_id integer Steam app ID of the game (0 when none).
banner_url string Absolute URL to the 460×215 game banner.
thumb_url string Absolute URL to the 120×45 thumbnail.
total integer Total number of servers matching the filter.
limit integer Limit used for this response.
offset integer Offset used.
count integer Number of servers in this response (≤ limit).
servers array Array of server objects. Sorted by player count descending.
servers[].id integer Numeric server ID in our database.
servers[].name string Server name.
servers[].ip string IPv4 address.
servers[].hostname string Original hostname (if submitted via DNS, empty for direct IP submissions).
servers[].port integer Game port (connect).
servers[].query_port integer Query port (A2S).
servers[].addr string Combined ip:port (game port).
servers[].players integer Current player count.
servers[].max_players integer Maximum player count.
servers[].map string Current map (empty if unavailable).
servers[].gamemode string Game mode (empty if unavailable).
servers[].version string Game version on the server.
servers[].gametime string In-game time on the server.
servers[].days string Days since server start (game-specific).
servers[].password boolean Password-protected.
servers[].official boolean Official server.
servers[].country string ISO 3166-1 alpha-2 country code (Geo-IP).
servers[].online boolean Server responded successfully on last fetch.
servers[].rank integer Rank in the global list (sorted by player count).
servers[].fetched_at integer Unix timestamp of last successful query.
servers[].first_seen_at integer Unix timestamp of first registration.
servers[].connect_url string Steam connect URL (steam://connect/...) when supported, null otherwise.
servers[].detail_url string Absolute URL to the server detail page.
servers[].owner object|null Verified owner if present, null otherwise. 
{
  "game": "arksa",
  "game_label": "Example Game",
  "app_id": 0,
  "banner_url": "https://query.games/assets/img/games/arksa/banner.jpg",
  "thumb_url":  "https://query.games/assets/img/games/arksa/thumb.jpg",
  "total": 12483,
  "limit": 100,
  "offset": 0,
  "count": 1,
  "servers": [
    {
      "id": 1,
      "name": "My Awesome Server",
      "ip": "1.2.3.4",
      "hostname": "play.example.com",
      "port": 28015,
      "query_port": 28015,
      "addr": "1.2.3.4:28015",
      "players": 120,
      "max_players": 200,
      "map": "Navezgane",
      "gamemode": "",
      "version": "1.0.0.0",
      "gametime": "12:00",
      "days": "3",
      "password": false,
      "official": false,
      "country": "DE",
      "online": true,
      "rank": 1,
      "fetched_at": 1714000000,
      "first_seen_at": 1700000000,
      "connect_url": "steam://connect/1.2.3.4:28015",
      "detail_url": "https://query.games/servers/arksa/1",
      "owner": {
        "name": "SteamUsername",
        "steam_id": "76561198000000000",
        "avatar_url": "https://…"
      }
    }
  ]
}
Returns details for a single server by its numeric ID. Includes owner information if the server has been claimed and verified.

At least one of id or addr must be provided. If both are sent, id takes precedence.

Parameter Type Required Default Description
id integer id OR addr – Numeric server ID from the database
addr string id OR addr – Address as ip:port or hostname:port. IP form matches against game-port or query-port (e.g. 1.2.3.4:28015); hostname form matches the original submission hostname (e.g. play.example.com:25565).
Response fields
Field Type Description
id integer Numeric server ID in our database.
game string Slug of the game (e.g. arkse, conanexiles).
game_label string Display name of the game.
app_id integer Steam app ID of the game (0 when none).
name string Server name.
ip string IPv4 address.
hostname string Original hostname (if submitted via DNS, empty for direct IP submissions).
port integer Game port (connect).
query_port integer Query port (A2S).
addr string Combined ip:port (game port).
players integer Current player count.
max_players integer Maximum player count.
map string Current map (empty if unavailable).
gamemode string Game mode (empty if unavailable).
version string Game version on the server.
gametime string In-game time on the server.
days string Days since server start (game-specific).
password boolean Password-protected.
official boolean Official server.
country string ISO 3166-1 alpha-2 country code (Geo-IP).
online boolean Server responded successfully on last fetch.
rank integer Rank in the global list (sorted by player count).
fetched_at integer Unix timestamp of last successful query.
first_seen_at integer Unix timestamp of first registration.
banner_url string Absolute URL to the 460×215 game banner.
thumb_url string Absolute URL to the 120×45 thumbnail.
connect_url string Steam connect URL (steam://connect/...) when supported, null otherwise.
detail_url string Absolute URL to the server detail page.
owner object|null Verified owner if present, null otherwise. 
{
  "id": 1,
  "game": "arksa",
  "game_label": "Example Game",
  "app_id": 0,
  "name": "My Server",
  "ip": "1.2.3.4",
  "hostname": "play.example.com",
  "port": 28015,
  "query_port": 28015,
  "addr": "1.2.3.4:28015",
  "players": 120,
  "max_players": 200,
  "map": "Navezgane",
  "gamemode": "",
  "version": "1.0.0.0",
  "gametime": "12:00",
  "days": "3",
  "password": false,
  "official": false,
  "country": "DE",
  "online": true,
  "rank": 1,
  "fetched_at": 1714000000,
  "first_seen_at": 1700000000,
  "banner_url": "https://query.games/assets/img/games/arksa/banner.jpg",
  "thumb_url":  "https://query.games/assets/img/games/arksa/thumb.jpg",
  "connect_url": "steam://connect/1.2.3.4:28015",
  "detail_url":  "https://query.games/servers/arksa/1",
  "owner": {
    "name": "SteamUsername",
    "steam_id": "76561198000000000",
    "avatar_url": "https://…"
  }
}
Returns player count history for a server. Older data is automatically compacted (hourly snapshots after 24h, daily after 7 days).

At least one of id or addr must be provided. If both are sent, id takes precedence.

Parameter Type Required Default Description
id integer id OR addr – Numeric server ID
addr string id OR addr – Address as ip:port or hostname:port. IP form matches against game-port or query-port (e.g. 1.2.3.4:28015); hostname form matches the original submission hostname (e.g. play.example.com:25565).
hours integer No 24 Time range in hours, 1–720 (max. 30 days)
Response fields
Field Type Description
server_id integer Numeric server ID.
hours integer Time range used in hours.
from integer Unix timestamp start.
to integer Unix timestamp end.
count integer Number of data points in points.
peak integer Peak player count in the range.
avg number Average player count in the range.
points array Time series sorted ascending.
points[].timestamp integer Unix timestamp of the data point.
points[].players integer Player count at this point.
points[].max_players integer Max player count at this point. 
{
  "server_id": 1,
  "hours": 24,
  "from": 1714000000,
  "to":   1714086400,
  "count": 24,
  "peak": 145,
  "avg": 87.3,
  "points": [
    { "timestamp": 1714000000, "players": 120, "max_players": 200 },
    { "timestamp": 1714003600, "players": 98,  "max_players": 200 }
  ]
}

Error responses always contain an error field (short code) and message (plain English description). Status codes follow HTTP conventions.

{
  "error": "invalid_addr",
  "message": "Use format ip:port, e.g. 1.2.3.4:28015"
}
JavaScript (fetch)
fetch('https://query.games/api/v1/servers?game=arksa&limit=10', {
  headers: {
    'Authorization': 'Bearer qg_your_key'
  }
})
  .then(r => r.json())
  .then(data => console.log(data.servers));
Python (requests)
import requests

resp = requests.get(
    'https://query.games/api/v1/servers',
    params={'game': 'arksa', 'limit': 10},
    headers={'Authorization': 'Bearer qg_your_key'}
)
data = resp.json()
print(data['servers'])
cURL
curl -H "Authorization: Bearer qg_your_key" \
  "https://query.games/api/v1/servers?game=arksa&limit=10"
PHP
$ctx = stream_context_create(['http' => [
  'header' => 'Authorization: Bearer qg_your_key'
]]);
$data = json_decode(file_get_contents(
  'https://query.games/api/v1/servers?game=arksa',
  false, $ctx
), true);
print_r($data['servers']);