ARK Status API Documentation

Welcome to the ARK Status API. Our API provides programmatic access to near real-time ARK: Survival Ascended server data, statistics, and analytics.

Getting Started

To use the API, you'll need an API key. Generate your API key in your account settings.

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 Unlimited* +100%

Per-Endpoint Limits

Endpoint Free Premium
/servers (listing) 10/min Unlimited*
/servers/{id} 10/min Unlimited*
/servers/{id}/history 5/min Unlimited*
/servers/{id}/preview 10/min Unlimited*
/statistics/* 5/min Unlimited*

How Rate Limiting Works

  • You must stay within BOTH your global limit AND per-endpoint limits
  • Burst allowance lets you temporarily exceed limits for traffic spikes
  • 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 - Reset time (Unix timestamp)
  • X-RateLimit-Endpoint-Limit - Endpoint-specific limit
  • X-RateLimit-Endpoint-Remaining - Endpoint requests remaining
  • X-RateLimit-Tier - Your current tier

* Premium tier limits are set very high to support any reasonable use case. Fair use policy applies to prevent abuse.

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 will return {"name": "...", "game_mode": "PVE", "platform": "PC"}

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
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

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",
      "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",
      "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|name}

Get detailed information about a specific server. You can use either the numeric server ID or the server name.

Usage Notes
  • Server names must be URL-encoded if they contain spaces or special characters
  • Both numeric IDs and server names are supported
  • Server names are case-sensitive

Example Requests:

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

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

# Using server name with spaces (URL-encoded)
curl -H "X-API-Key: your_key" \
  "https://arkstatus.com/api/v1/servers/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",
    "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|name}/history

Get historical data for a server. Supports both numeric ID and server name.

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|name}/preview

Get lightweight server information for quick preview. Ideal for tooltips or quick status checks.

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"

# Get server details by name
curl -H "X-API-Key: your_api_key" \
  "https://arkstatus.com/api/v1/servers/NA-PVE-GenOne"

# Get server history by name (URL-encoded)
curl -H "X-API-Key: your_api_key" \
  "https://arkstatus.com/api/v1/servers/EU%20PVP%20Scorched%20Earth/history?hours=48"

Support

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