How to check multiple Minecraft servers in one API request

On a network status page, the lobby can be online while a game server is unreachable. Send public connection addresses together using POST /api/v1/status/bulk. The response preserves input order and gives each target its own status_code.

Send Java and Bedrock targets together

Save the example as status.mjs and run node status.mjs with Node.js 22. The reserved example.invalid name demonstrates an unreachable target alongside the other results.

const servers = [
  { address: 'mc.hypixel.net' },
  { address: 'geo.hivebedrock.network', bedrock: true },
  { address: 'example.invalid' },
];

const response = await fetch('https://mcapi.tr/api/v1/status/bulk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ servers }),
  signal: AbortSignal.timeout(15000),
});

if (response.status === 429) {
  throw new Error('Rate limited. Retry-After: ' + (response.headers.get('Retry-After') ?? 'unknown'));
}
if (!response.ok) throw new Error('HTTP ' + response.status);

const { data } = await response.json();
console.table(data.map(({ address, status_code, data: server }) => ({
  address,
  status: status_code === 200 && server.online
    ? (server.stale ? 'stale' : 'online')
    : (status_code === 404 ? 'unreachable' : 'error'),
  players: server.players?.online ?? null,
})));

Read each result before updating your dashboard

• The HTTP response can be 200 while an individual target returns 404. Update each row from its own result.
• Label stale: true as last known status. An absent player count is unknown.
• A request accepts up to 50 targets, with six bulk requests per minute per IP. When many visitors share the same list, fetch it once on your backend and reuse the result briefly. Honor Retry-After on 429 when the header is present.

For servers behind Velocity or BungeeCord, query the public proxy addresses your players use. For per-mode counts on private Paper backends, collect the data inside your network.

Sources and related guides

• MCAPI API documentation
• Display player count on a website
• Community discussion (SpigotMC)