API Documentation - ARK Status

Base URL

https://arkstatus.com/api/v1

Authentication

Include your API key in the request header:

X-API-Key: ark_your_api_key_here

Alternatively, you can use the Authorization header with Bearer token:

Authorization: Bearer ark_your_api_key_here

Rate Limits

Our API uses a hybrid rate limiting approach with both global and per-endpoint limits.

Global Limits (Total across all endpoints)

Tier	Requests/Minute	Burst Allowance
Free (with API Key)	10	None
Premium	120	None

Per-Endpoint Limits

Endpoint	Free	Premium
`/servers` (listing)	10/min	60/min
`/servers/{id}`	10/min	120/min
`/servers/{id}/history`	5/min	30/min
`/servers/{id}/preview`	10/min	120/min
`/statistics/*`	5/min	30/min

How Rate Limiting Works

You must stay within BOTH your global limit AND per-endpoint limits
Burst allowance is currently disabled, so configured limits stay predictable
Rate limits reset every minute

Rate limit information is included in response headers:

X-RateLimit-Limit - Global request limit
X-RateLimit-Remaining - Global requests remaining
X-RateLimit-Reset - Seconds until rate limit window resets
X-RateLimit-Endpoint-Limit - Endpoint-specific limit
X-RateLimit-Endpoint-Remaining - Endpoint requests remaining
X-RateLimit-Tier - Your current tier

Premium tier limits are higher than the free tier and remain subject to fair use.

Field Transformations

The API transforms certain database field names for consistency and clarity:

Database Field	API Response Field	Description
`server_name`	`name`	Server name
`is_pve`	`game_mode`	Converted to "PVE" or "PVP" string
`platform_type`	`platform`	Platform identifier
`ping`	`status`	NULL or ≤ 0 = "offline", otherwise "online"

Important Note

When using the fields parameter, specify the database field names (e.g., server_name, is_pve), not the transformed names.

Example: ?fields=server_name,is_pve,platform_type,mod_ids,mod_file_ids will return {"name": "...", "game_mode": "PVE", "platform": "PC", "mod_ids": "123,456", "mod_file_ids": "987,654"}

Endpoints

Server Data

GET /servers

Get a paginated list of servers with optional filtering.

Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (max: 200, default: 50)
`search`	string	Search servers by name
`status`	string	Filter by status: online, offline, all
`server_type`	string	Filter by server type: official, unofficial, all (default: all)
`map`	string	Filter by map name
`game_mode`	string	Filter by game mode: PVP, PVE, PVPVE, all
`platform`	string	Filter by platform: PC, PS5, XSX, all
`min_players`	integer	Filter servers with at least this many players
`max_players`	integer	Filter servers with at most this many players
`sort`	string	Sort by: name, players, uptime, last_seen
`order`	string	Sort order: asc, desc
`fields`	string	Comma-separated list of fields to return. Available: id, server_name, ip, port, map, players, max_players, status, is_pve, platform_type, version, day_number, last_updated, mod_ids, mod_file_ids

Example Request:

curl -H "X-API-Key: your_key" \
  "https://arkstatus.com/api/v1/servers?status=online&platform=PC&sort=players"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "name": "NA-PVP-Ragnarok-OfficialServer123",
      "map": "Ragnarok_WP",
      "status": "online",
      "players": 68,
      "max_players": 70,
      "player_percentage": 97.14,
      "platform": "PC",
      "game_mode": "PVP",
      "version": "947.15",
      "mod_ids": "928621,953154",
      "mod_file_ids": "930494764,930494765",
      "day_number": 342,
      "last_updated": "2025-01-07T12:30:45Z"
    },
    {
      "id": 23456,
      "name": "EU-PVE-TheIsland-Community",
      "map": "TheIsland_WP",
      "status": "online",
      "players": 45,
      "max_players": 100,
      "player_percentage": 45.0,
      "platform": "PC",
      "game_mode": "PVE",
      "version": "947.15",
      "mod_ids": "",
      "mod_file_ids": "",
      "day_number": 287,
      "last_updated": "2025-01-07T12:29:30Z"
    }
  ],
  "meta": {
    "timestamp": 1736255445,
    "version": "v1",
    "pagination": {
      "total": 1247,
      "count": 2,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 25,
      "has_more": true
    },
    "response_time_ms": 125.8,
    "cached": false,
    "filters_applied": {
      "status": "online",
      "platform": "PC"
    }
  }
}

GET /servers/{id}

Get detailed information about a specific server by numeric server ID. To find a server by name, use /servers?search=... first and then call this endpoint with the returned id.

Usage Notes

Use /servers?search=... for name searches.
Do not put the search text directly after ?; the query parameter must be named search.
Use the numeric id from the search result for details, history, and preview requests.

Example Requests:

# Using numeric ID
curl -H "X-API-Key: your_key" \
  "https://arkstatus.com/api/v1/servers/12345"

# Search by server name
curl -H "X-API-Key: your_key" \
  "https://arkstatus.com/api/v1/servers?search=NA-PVE-GenOne"

# Search by server name with spaces or special characters
curl -H "X-API-Key: your_key" \
  "https://arkstatus.com/api/v1/servers?search=NA%20PVE%20Island%20123"

Example Response:

{
  "success": true,
  "data": {
    "id": 12345,
    "name": "NA-PVE-GenOne",
    "map": "TheIsland_WP",
    "status": "online",
    "players": 45,
    "max_players": 70,
    "player_percentage": 64.29,
    "platform": "PC",
    "game_mode": "PVE",
    "version": "947.15",
    "mod_ids": "928621,953154",
    "mod_file_ids": "930494764,930494765",
    "ping": 32,
    "day_number": 342,
    "last_updated": "2025-01-07T12:30:45Z",
    "last_snapshot": "2025-01-07T12:30:00Z",
    "connection_info": {
      "ip": "192.168.1.100",
      "port": 27015,
      "query_port": 27016
    },
    "statistics": {
      "7_days": {
        "uptime_percentage": 98.7,
        "average_players": 38.5,
        "peak_players": 68
      },
      "30_days": {
        "uptime_percentage": 94.5,
        "average_players": 35.2,
        "peak_players": 85
      }
    }
  },
  "meta": {
    "timestamp": 1736255445,
    "version": "v1",
    "response_time_ms": 12.5
  }
}

GET /servers/{id}/history

Get historical data for a server by numeric server ID. To find a server by name, use /servers?search=... first and then call this endpoint with the returned id.

Parameters

Parameter	Type	Description
`hours`	integer	Hours of history (1-168, default: 24)
`resolution`	string	Data resolution: auto, 5min, 15min, 1hour, 1day

Example Response:

{
  "success": true,
  "data": {
    "server_id": 12345,
    "time_range": {
      "hours": 24,
      "start": "2025-01-06T12:30:00Z",
      "end": "2025-01-07T12:30:00Z"
    },
    "resolution": "15min",
    "data": [
      {
        "timestamp": "2025-01-07T12:15:00",
        "players": {
          "peak": 48,
          "average": 45.2,
          "minimum": 42
        },
        "uptime": 100.0,
        "data_points": 3
      },
      {
        "timestamp": "2025-01-07T12:00:00",
        "players": {
          "peak": 45,
          "average": 43.5,
          "minimum": 41
        },
        "uptime": 100.0,
        "data_points": 3
      }
    ]
  },
  "meta": {
    "timestamp": 1736255445,
    "version": "v1",
    "response_time_ms": 87.3
  }
}

GET /servers/{id}/preview

Get lightweight server information for quick preview by numeric server ID. To find a server by name, use /servers?search=... first and then call this endpoint with the returned id.

Example Request:

curl -H "X-API-Key: your_key" \
  "https://arkstatus.com/api/v1/servers/12345/preview"

Example Response:

{
  "success": true,
  "data": {
    "id": 12345,
    "name": "NA-PVE-GenOne",
    "status": "online",
    "players": {
      "current": 45,
      "max": 70,
      "percentage": 64.29
    },
    "map": "TheIsland_WP",
    "game_mode": "PVE",
    "last_seen": "2025-01-07T12:30:00Z",
    "stats_7d": {
      "uptime": 98.7,
      "avg_players": 38.5,
      "peak_players": 68
    }
  },
  "meta": {
    "timestamp": 1736255445,
    "version": "v1",
    "response_time_ms": 8.2
  }
}

Statistics

GET /statistics/player-stats

Get global player statistics and trends over time.

Parameters

Parameter	Type	Description
`interval`	string	Aggregation interval: hourly, daily, weekly (default: daily)
`days`	integer	Days to analyze (1-30, default: 7)

Example Response:

{
  "success": true,
  "data": {
    "interval": "daily",
    "days_analyzed": 7,
    "data": [
      {
        "period": "2025-01-01",
        "active_servers": 1247,
        "total_players": 45892,
        "avg_players_per_server": 36.8,
        "peak_concurrent": 52103,
        "occupancy_rate": 78.5
      },
      // ... more periods
    ]
  }
}

GET /statistics/server-distribution

Get distribution of servers by various attributes.

Parameters

Parameter	Type	Description
`group_by`	string	Grouping attribute: map, game_mode, region, platform (default: map)

Example Response:

{
  "success": true,
  "data": {
    "group_by": "map",
    "data": {
      "distribution": [
        {
          "name": "TheIsland_WP",
          "server_count": 387,
          "player_count": 14235,
          "avg_players": 36.8,
          "online_count": 352,
          "online_percentage": 91.0,
          "avg_uptime": 94.5,
          "server_percentage": 31.0,
          "player_percentage": 28.5
        },
        // ... more maps
      ],
      "totals": {
        "servers": 1247,
        "players": 49892,
        "online": 1134
      }
    }
  }
}

GET /statistics/platform-stats

Get statistics grouped by platform (PC, PS5, XSX).

This endpoint requires no parameters.

Example Response:

{
  "success": true,
  "data": {
    "platforms": [
      {
        "platform": "PC",
        "metrics": {
          "server_count": 892,
          "online_count": 823,
          "online_percentage": 92.3,
          "total_players": 35672,
          "avg_players_per_server": 40.0,
          "peak_players": 892
        },
        "performance": {
          "avg_uptime_7d": 95.2,
          "avg_uptime_30d": 93.8,
          "avg_players_7d": 38.5,
          "peak_players_7d": 68
        }
      },
      // ... other platforms
    ]
  }
}

Common Field Descriptions

Field	Type	Description
`id`	integer	Unique server identifier
`name`	string	Server name (case-sensitive, may contain spaces)
`status`	string	Server status: "online" or "offline"
`map`	string	Map identifier (e.g., TheIsland_WP, Ragnarok_WP)
`game_mode`	string	Game mode: PVP, PVE, or PVPVE
`platform`	string	Platform: PC, PS5, or XSX
`uptime_7d`	float	7-day uptime percentage (0.0 to 1.0)
`uptime_30d`	float	30-day uptime percentage (0.0 to 1.0)
`last_seen`	string	ISO 8601 timestamp of last successful query
`day_number`	integer	Current in-game day number on the server

Response Format

All API responses follow a consistent JSON structure:

Success Response:

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": 1234567890,
    "version": "v1",
    "response_time_ms": 45.2
  }
}

Error Response:

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED"
  },
  "meta": {
    "timestamp": 1234567890,
    "version": "v1"
  }
}

Code Examples

cURL JavaScript Python PHP

                                # Get online PC servers sorted by players
curl -H "X-API-Key: your_api_key" \
  "https://arkstatus.com/api/v1/servers?status=online&platform=PC&sort=players"

# Get server details by ID
curl -H "X-API-Key: your_api_key" \
  "https://arkstatus.com/api/v1/servers/12345"

# Search by server name, then use the returned id
curl -H "X-API-Key: your_api_key" \
  "https://arkstatus.com/api/v1/servers?search=NA-PVE-GenOne"

# Get server history by ID
curl -H "X-API-Key: your_api_key" \
  "https://arkstatus.com/api/v1/servers/12345/history?hours=48"
                            

                                // Using fetch API
const API_KEY = 'your_api_key';
const BASE_URL = 'https://arkstatus.com/api/v1';

// Get servers
async function getServers() {
  const response = await fetch(`${BASE_URL}/servers?status=online`, {
    headers: {
      'X-API-Key': API_KEY
    }
  });
  
  const data = await response.json();
  console.log(data);
}

// Search servers by name
async function searchServersByName(serverName) {
  const params = new URLSearchParams({ search: serverName });
  const response = await fetch(`${BASE_URL}/servers?${params}`, {
    headers: {
      'X-API-Key': API_KEY
    }
  });

  return response.json();
}

// Get server details by numeric ID
async function getServerDetails(serverId) {
  const response = await fetch(`${BASE_URL}/servers/${encodeURIComponent(serverId)}`, {
    headers: {
      'X-API-Key': API_KEY
    }
  });

  const data = await response.json();
  return data;
}

// Examples
searchServersByName('NA-PVE-GenOne'); // Search by name
getServerDetails(12345);              // Details by ID
                            

                                import requests

API_KEY = 'your_api_key'
BASE_URL = 'https://arkstatus.com/api/v1'

headers = {
    'X-API-Key': API_KEY
}

# Get servers
response = requests.get(
    f'{BASE_URL}/servers',
    headers=headers,
    params={
        'status': 'online',
        'platform': 'PC',
        'sort': 'players'
    }
)

servers = response.json()

# Get server details by ID
server_id = 12345
response = requests.get(
    f'{BASE_URL}/servers/{server_id}',
    headers=headers
)

# Search by server name, then use the returned id
server_name = 'NA PVE Island 123'
response = requests.get(
    f'{BASE_URL}/servers',
    headers=headers,
    params={'search': server_name}
)

search_results = response.json()
server_id = search_results['data'][0]['id']
response = requests.get(
    f'{BASE_URL}/servers/{server_id}',
    headers=headers
)

server_details = response.json()
                            

                                <?php
$apiKey = 'your_api_key';
$baseUrl = 'https://arkstatus.com/api/v1';

// Initialize cURL
$ch = curl_init();

// Set common options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey
]);

// Get servers
$params = http_build_query([
    'status' => 'online',
    'platform' => 'PC',
    'sort' => 'players'
]);

curl_setopt($ch, CURLOPT_URL, $baseUrl . '/servers?' . $params);
$response = curl_exec($ch);
$servers = json_decode($response, true);

// Get server details by ID
$serverId = 12345;
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/servers/' . $serverId);
$response = curl_exec($ch);
$serverDetails = json_decode($response, true);

// Search by server name, then use the returned id
$serverName = 'NA PVE Island 123';
$params = http_build_query(['search' => $serverName]);
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/servers?' . $params);
$response = curl_exec($ch);
$searchResults = json_decode($response, true);

$serverId = $searchResults['data'][0]['id'] ?? null;
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/servers/' . $serverId);
$response = curl_exec($ch);
$serverDetails = json_decode($response, true);

curl_close($ch);
                            

Support

Need help with the API? We're here to assist:

Discord: Join our Discord

ARK Status API Documentation

Getting Started

Base URL

Authentication

Rate Limits

Global Limits (Total across all endpoints)

Per-Endpoint Limits

How Rate Limiting Works

Field Transformations

Important Note

Endpoints

Server Data

Statistics

Common Field Descriptions

Response Format

Code Examples

Support