Core Endpoints
Access live server metrics, player rosters, and regional routing data through our RESTful v2 interface. All requests require a valid API key passed via the Authorization: Bearer header.
/v2/servers
Retrieve paginated list of active game servers. Supports filtering by game title, region, and minimum player count.
Parameters: game (string), region (string), limit (int, max 100), offset (int)
Auth: Bearer Token required
/v2/servers/{server_id}
Fetch detailed telemetry for a specific server instance, including tick rate, map cycle, and admin rules.
Parameters: server_id (path, string)
Auth: Bearer Token required
/v2/presence/heartbeat
Submit periodic status updates from your dedicated server to maintain visibility in the global directory.
Parameters: payload (JSON body: ip, port, query_port, game_id)
Auth: Server Secret Key in body
Request & Response Samples
Standard JSON payloads with strict schema validation. All timestamps follow ISO 8601 UTC format.
GET /v2/servers?game=cs2®ion=eu-west&limit=2
Request Headers:
Authorization: Bearer sk_live_9f8a2c1d4e5b6f7g8h9j0k
Accept: application/json
Response (200 OK):
{
"data": [
{
"server_id": "srv_8821903",
"hostname": "PulseHQ | Competitive 5v5 #1",
"ip": "185.224.128.44",
"port": 27015,
"players": {"current": 9, "max": 10},
"map": "de_mirage",
"tickrate": 64,
"updated_at": "2024-05-12T14:32:08Z"
},
{
"server_id": "srv_8821904",
"hostname": "PulseHQ | Casual Retakes",
"ip": "185.224.128.45",
"port": 27016,
"players": {"current": 6, "max": 12},
"map": "de_inferno",
"tickrate": 64,
"updated_at": "2024-05-12T14:31:55Z"
}
],
"pagination": {"total": 142, "next_offset": 2}
}
Error Handling (429 Too Many Requests)
Response Payload:
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "You have exceeded the 120 requests per minute threshold.",
"retry_after": 42
}
}
Rate Limits & Throttling
API access is tiered based on your subscription plan. Limits are calculated per API key using a sliding window algorithm.
Free Tier
120 requests / minute
Ideal for personal projects, small community browsers, and development testing. Burst allowance capped at 25 requests per second.
Pro Tier
1,000 requests / minute
Designed for active server networks and commercial matchmaking platforms. Includes priority queue routing and webhook delivery guarantees.
Enterprise Tier
5,000 requests / minute (or custom)
Dedicated infrastructure with sub-50ms latency. Contact sales@serverpulse.io to configure custom quotas, IP whitelisting, and SLA-backed uptime.