Skip to content
For ownersAdd a server

API for developers

Catalog data for bots, clan websites and widgets: server status, a game's server lists, online history, games and wipes. The numbers are the same as on the site — after removing bots and copies. Online we do not trust is never passed off as real in the API: every server has a trust field.

Addresshttps://battlemetrics.ru/api/v1
  1. Sign in and issue a key — below, in the section “Keys and limits”.
  2. Pass it in the header Authorization: Bearer bm_live_….
  3. The response is JSON in UTF-8, times are ISO 8601 in UTC, fields are snake_case.

Addresses /api/… without v1 serve the site's own pages. They have no versions and no compatibility promises — do not build anything on them: they will break without warning.

Request
curl https://battlemetrics.ru/api/v1/servers/51716811 \
  -H "Authorization: Bearer bm_live_••••"
Response · 200
{
  "id": 51716811,
  "game": "minecraft",
  "name": "DonutSMP.net ѕᴜʀᴠɪᴠᴀʟ",
  "address": "40.223.14.114:25565",
  "ip": "40.223.14.114",
  "port": 25565,
  "query_port": 25565,
  "map": null,
  "country": "us",
  "online": true,
  "players": 26758,
  "max_players": 50000,
  "queue": 0,
  "trust": "confirmed",
  "uptime": 0.968,
  "last_seen": "2026-10-13T00:39:09.699Z",
  "last_wipe": null,
  "promoted": false,
  "url": "https://battlemetrics.ru/game/minecraft/server/51716811",
  "game_name": "Minecraft: Java Edition",
  "players_raw": 26758,
  "bots": 0,
  "canonical_id": null,
  "flagged_at": null,
  "version": "Velocity 1.7.2-26.3",
  "rating": null,
  "review_count": 0,
  "first_seen": "2026-10-08T18:28:30.526Z"
}

Keys and limits

A key is free and issued instantly. You can have three active keys: for example, for a production bot, for development and a spare one. The full key is shown only once — we store only its hash. Lost it? Revoke it and issue a new one.

The limit is 60 requests per minute per key. After a pause you can make up to 60 in a row, then requests refill at one per second. The remainder is shown in every response, in the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; when exceeded, a 429 comes with the header Retry-After.

Free: 60 requests/minWith promotion: 600 requests/min · soon

Data is updated once a minute, so responses can be cached for 15 seconds — asking more often is pointless. The key is secret: do not put it into the code of a page opened by a browser — anyone will see it. If you show our data on your site, add a link to battlemetrics.ru; this is a condition of the terms of use, clause 8.

Request
curl -i https://battlemetrics.ru/api/v1/servers/51716811 \
  -H "Authorization: Bearer bm_live_••••"
Response headers
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-ratelimit-limit: 60
x-ratelimit-remaining: 59
x-ratelimit-reset: 1
cache-control: private, max-age=15

Errors

Any error is JSON of one shape: code for programs, message for humans. The message may change, the code does not.

Codes
400 bad_requestparametersA parameter of the wrong kind: the message says which one and what we expect
401 unauthorizedkeyNo key, it does not look like ours, or no such key exists
401 key_revokedkeyThe key was revoked by its owner
403 account_blockedkeyThe key owner's account is closed
403 forbiddenkeyServer votes — only with a key from the account of its verified owner
404 not_founddataNo such server, game or method
409 untrusteddataWe do not provide the online history of a server we do not trust
429 rate_limitedlimitLimit exceeded; how long to wait is in Retry-After
500 internalusAn error on our side; it is already in the log
502 · 503 · 504usThe site is not responding or is under maintenance — try again later

Thirty requests with an invalid key per minute from one address is abuse, not a typo: after that the address gets 429 until the minute passes.

Request
curl https://battlemetrics.ru/api/v1/servers/51716811 \
  -H "Authorization: Bearer bm_live_••••"
Response · 429
{
  "error": {
    "code": "rate_limited",
    "message": "No more than 60 requests per minute per key."
  }
}
GET/v1/servers/{id}

Current server status. Online is only what our antifraud has verified; the server's raw value is returned in a separate field.

Response fields
playersint | nullVerified online. null if trust is not confirmed
players_rawintWhat the server reports itself
trustenumconfirmed · suspicious · mirror · farm
last_wipedatetimeTime of the last wipe, ISO 8601
promotedboolA paid placement is active now
id · game · nameint · stringNumber, game code, name
addressstringConnection address: ip:port
port · query_portintGame port and A2S query port
map · countrystring | nullMap and country code
onlineboolWhether the server is responding now
max_players · queueintSlots and queue
botsintBots the server reported
uptimefloatShare of time online over the week, from 0 to 1
canonical_idint | nullFor a copy — the original we show
flagged_atdatetime | nullWhen the flag was set
rating · review_countfloat | null · intRating from reviews and their count
first_seen · last_seendatetimeWhen first seen and when it last responded
urlstringServer page on the site
Free: 60 requests/minWith promotion: 600 requests/min · soon
Request
curl https://battlemetrics.ru/api/v1/servers/51716811 \
  -H "Authorization: Bearer bm_live_••••"
Response · 200
{
  "id": 51716811,
  "game": "minecraft",
  "name": "DonutSMP.net ѕᴜʀᴠɪᴠᴀʟ",
  "address": "40.223.14.114:25565",
  "ip": "40.223.14.114",
  "port": 25565,
  "query_port": 25565,
  "map": null,
  "country": "us",
  "online": true,
  "players": 26758,
  "max_players": 50000,
  "queue": 0,
  "trust": "confirmed",
  "uptime": 0.968,
  "last_seen": "2026-10-13T00:39:09.699Z",
  "last_wipe": null,
  "promoted": false,
  "url": "https://battlemetrics.ru/game/minecraft/server/51716811",
  "game_name": "Minecraft: Java Edition",
  "players_raw": 26758,
  "bots": 0,
  "canonical_id": null,
  "flagged_at": null,
  "version": "Velocity 1.7.2-26.3",
  "rating": null,
  "review_count": 0,
  "first_seen": "2026-10-08T18:28:30.526Z"
}
GET/v1/servers

A game's server list — the same as on the game page: only visible servers, by default only those responding now. Flagged servers are not listed.

Parameters
gamestringGame code, required. Codes are in GET /games
sortenumplayers · fill · ping · wipe · rank · name; default is players
pageintPage, from 1 to 100
per_pageenum20 · 50 · 100
countrystringCountry code: RU, DE…
mapstringExact map name
min_playersintAt least this many players
qstringPart of the name, 3 to 60 characters
offlinebool1 — also show those not responding
Response fields
total · pagesintHow many servers match and how many pages
servers[]arrayRows: the same fields as GET /servers/{id}, without players_raw, bots, rating and flag history
Request
curl https://battlemetrics.ru/api/v1/servers?game=rust&per_page=20 \
  -H "Authorization: Bearer bm_live_••••"
Response · 200
{
  "game": "rust",
  "page": 1,
  "per_page": 20,
  "total": 10033,
  "pages": 502,
  "servers": [
    {
      "id": 50208245,
      "game": "rust",
      "name": "Rusty Moose |US Mondays|",
      "address": "205.178.168.77:28010",
      "ip": "205.178.168.77",
      "port": 28010,
      "query_port": 28015,
      "map": "Moose Maps",
      "country": "us",
      "online": true,
      "players": 899,
      "max_players": 1000,
      "queue": 0,
      "trust": "confirmed",
      "uptime": 0.699,
      "last_seen": "2026-10-13T00:39:07.893Z",
      "last_wipe": "2026-10-12T18:59:04.000Z",
      "promoted": false,
      "url": "https://battlemetrics.ru/game/rust/server/50208245"
    },
    {
      "id": 50209237,
      "game": "rust",
      "name": "Rustoria.co - US Mondays",
      "address": "208.103.169.85:28010",
      "ip": "208.103.169.85",
      "port": 28010,
      "query_port": 28015,
      "map": "Procedural Map",
      "country": "us",
      "online": true,
      "players": 766,
      "max_players": 800,
      "queue": 0,
      "trust": "confirmed",
      "uptime": 0.991,
      "last_seen": "2026-10-13T00:39:07.893Z",
      "last_wipe": "2026-10-12T18:56:33.000Z",
      "promoted": false,
      "url": "https://battlemetrics.ru/game/rust/server/50209237"
    },
    … more 18
  ]
}
GET/v1/servers/{id}/history

Online history with the same step as the chart on the server page. A point is the average online over the step among successful samples; a step where the server never responded is skipped, not recorded as zero. We do not return history for flagged servers — 409.

Parameters
periodenum24h — 5-minute step · 7d — hourly step · 30d — daily step
Response fields
step_secintPoint step in seconds
points[].tdatetimeStart of the step
points[].playersintAverage online over the step
Request
curl https://battlemetrics.ru/api/v1/servers/51716811/history?period=24h \
  -H "Authorization: Bearer bm_live_••••"
Response · 200
{
  "server_id": 51716811,
  "period": "24h",
  "step_sec": 300,
  "points": [
    {
      "t": "2026-10-12T00:40:00.000Z",
      "players": 30903
    },
    {
      "t": "2026-10-12T00:45:00.000Z",
      "players": 30947
    },
    {
      "t": "2026-10-12T00:50:00.000Z",
      "players": 30761
    },
    … more 285
  ]
}
GET/v1/servers/{id}/votes

For a server plugin: whether the player voted in the last 24 hours and whether there is an unclaimed reward for it. The player enters a nickname when voting on the server page. Only with a key from the account of this server's verified owner — otherwise 403. Without nick — the month's vote count and rank in the game.

Parameters
nickstringIn-game nickname, up to 32 characters; case-insensitive
Response fields
votedboolVoted within the last 24 hours
unclaimedintHow many votes in the last 24 hours still have no reward issued
last_vote_atdatetime · nullWhen they last voted within 24 hours
votes_monthintThis nickname's votes in the calendar month
Request
curl https://battlemetrics.ru/api/v1/servers/{id}/votes?nick=Steve \
  -H "Authorization: Bearer bm_live_••••"
Response · 200
{
  "server": 123,
  "nick": "Steve",
  "voted": true,
  "last_vote_at": "2026-09-27T10:15:00.000Z",
  "unclaimed": 1,
  "votes_month": 12
}
GET/v1/servers/{id}/votes/claim

The plugin issued a reward — mark the vote so it is not issued twice. The nickname's most recent unclaimed vote within 24 hours is marked; claimed: false — there is nothing to claim. Body — JSON {"nick": "…"}.

Response fields
claimedboolReward marked
vote_atdatetime · nullWhen the marked vote was cast
Request
curl -X POST https://battlemetrics.ru/api/v1/servers/{id}/votes/claim \
  -H "Authorization: Bearer bm_live_••••" \
  -H "content-type: application/json" -d '{"nick":"Steve"}'
Response · 200
{
  "server": 123,
  "nick": "Steve",
  "claimed": true,
  "vote_at": "2026-09-27T10:15:00.000Z"
}
GET/v1/games

All catalog games and their online now. A game with no online at this minute stays in the list with zeros: its code is needed for GET /servers.

Response fields
code · namestringCode for other methods and the name
playersintVerified online of the game
servers_onlineintVisible servers responding now
servers_visibleintVisible servers in total
Request
curl https://battlemetrics.ru/api/v1/games \
  -H "Authorization: Bearer bm_live_••••"
Response · 200
{
  "games": [
    {
      "code": "fivem",
      "name": "FiveM",
      "players": 158466,
      "servers_online": 32725,
      "servers_visible": 106321,
      "url": "https://battlemetrics.ru/game/fivem"
    },
    {
      "code": "minecraft",
      "name": "Minecraft: Java Edition",
      "players": 73485,
      "servers_online": 1383,
      "servers_visible": 1485,
      "url": "https://battlemetrics.ru/game/minecraft"
    },
    {
      "code": "rust",
      "name": "Rust",
      "players": 49228,
      "servers_online": 10033,
      "servers_visible": 35911,
      "url": "https://battlemetrics.ru/game/rust"
    },
    … more 120
  ]
}
GET/v1/wipes

A game's wipes: those that happened or those promised. These are two different kinds of knowledge, and the fact field tells them apart: true — we observed the wipe ourselves, false — the date comes from the server description, i.e. the owner's promise.

Parameters
gamestringGame code, required
whenenumupcoming — promised · past — happened
hoursintWindow: up to 336 hours ahead or up to 168 back; default 24
limitintUp to 200 rows, default 50
Response fields
atdatetimeMoment of the wipe
factboolObservation (true) or promise (false)
cycleenum | nullweekly · biweekly · monthly · other
server_id · name · urlint · stringWhich server
Request
curl https://battlemetrics.ru/api/v1/wipes?game=rust&when=upcoming \
  -H "Authorization: Bearer bm_live_••••"
Response · 200
{
  "game": "rust",
  "when": "upcoming",
  "hours": 24,
  "wipes": [
    {
      "server_id": 278400,
      "name": "[BR/LATAM] Raidados.top 2X MAX4 | Vanilla+ | Wipe 10/10",
      "at": "2026-10-13T10:00:00.000Z",
      "fact": false,
      "cycle": "other",
      "players": 3,
      "max_players": 60,
      "country": "br",
      "url": "https://battlemetrics.ru/game/rust/server/278400"
    },
    {
      "server_id": 5449231,
      "name": "GOLD RUST X10/MAX5 | ДЛЯ НОВИЧКОВ",
      "at": "2026-10-13T10:00:00.000Z",
      "fact": false,
      "cycle": "other",
      "players": 1,
      "max_players": 100,
      "country": "ru",
      "url": "https://battlemetrics.ru/game/rust/server/5449231"
    },
    … more 5
  ]
}

The site uses cookies: the necessary ones for sign-in and the theme, plus the Yandex Metrica and LiveInternet visit counters — they show us how the site is used. We have no advertising cookies. More