List2Play

List2Play • Blog

List2Play API Documentation

Published Updated December 6, 2025
Complete guide to using the List2Play API to access server data, statistics, and information programmatically.

List2Play API Documentation

Overview

The List2Play API provides programmatic access to server statistics and management functions. The API is available at https://list2play.com/api/ base URL.

API Structure

The List2Play API is divided into two categories:

1. Public Endpoints

These endpoints are used by our frontend and do not require authentication:

  • /api/servers/{server}/stats/* - Server statistics endpoints

2. Authenticated Endpoints (API v1)

These endpoints are for external users and require API token authentication:

  • /api/v1/servers - Server list
  • /api/v1/meta/* - Meta information (game types, categories, countries)
  • /api/v1/servers/{server} - Server details
  • /api/v1/servers/{server}/votes - Server votes

Authentication

Public Endpoints

Public endpoints (/api/servers/{server}/stats/*) do not require authentication and can be used directly.

Authenticated Endpoints

Authenticated endpoints (/api/v1/*) require an API token, which you can obtain:

  1. Log in to your List2Play account
  2. Go to Profile Settings
  3. In the "API Access" section, generate an API token
  4. Use the token in all requests to /api/v1/* endpoints

How to use the token: Include the token in the Authorization header:

Authorization: YOUR_TOKEN

Or with Bearer prefix (both versions work):

Authorization: Bearer YOUR_TOKEN

Rate Limiting

The API has rate limiting:

  • 60 requests per minute per IP address or authenticated user ID
  • If you exceed the limit, you'll receive a 429 Too Many Requests response

Base URL

https://list2play.com/api

Public endpoints:

  • /api/servers/{server}/stats/*

Authenticated endpoints (v1):

  • /api/v1/*

Endpoints

1. Server Player Statistics

Get server player statistics over a specified time period.

Endpoint:

GET /api/servers/{server}/stats/players

Parameters:

Parameter Type Required Default Description
server integer Yes - Server ID (route parameter)
days integer No 14 Number of days to retrieve statistics for (1-365)
granularity string No auto Data granularity: day, hour, or 15min (automatically selected based on days)

Examples:

# Last 14 days statistics (daily granularity)
GET /api/servers/1/stats/players?days=14

# Last 7 days statistics
GET /api/servers/1/stats/players?days=7

# Last 24 hours statistics (15-minute granularity)
GET /api/servers/1/stats/players?days=1

# Last 30 days statistics
GET /api/servers/1/stats/players?days=30

Response Format:

When days > 1 (daily granularity):

{
  "server_id": 1,
  "range": {
    "from": "2025-11-01",
    "to": "2025-11-15",
    "days": 14
  },
  "granularity": "day",
  "series": [
    {
      "date": "2025-11-01",
      "max": 45,
      "average": 32,
      "min": 15,
      "peak_hour": 20,
      "members_max": null,
      "members_average": null,
      "members_min": null
    },
    {
      "date": "2025-11-02",
      "max": 48,
      "average": 35,
      "min": 18,
      "peak_hour": 21,
      "members_max": null,
      "members_average": null,
      "members_min": null
    }
  ]
}

When days = 1 (15-minute granularity):

{
  "server_id": 1,
  "range": {
    "from": "2025-11-15T00:00:00+00:00",
    "to": "2025-11-15T23:59:59+00:00",
    "days": 1
  },
  "granularity": "15min",
  "interval_minutes": 15,
  "series": [
    {
      "date": "00:00",
      "timestamp": "2025-11-15T00:00:00+00:00",
      "max": 25,
      "average": 20,
      "min": 15,
      "peak_hour": 0,
      "members_max": null,
      "members_average": null,
      "members_min": null
    }
  ]
}

Field Descriptions:

  • server_id - Server ID
  • range.from - Start date
  • range.to - End date
  • range.days - Number of days
  • granularity - Data granularity (day, 15min)
  • series - Statistics data array
    • date - Date or time (depending on granularity)
    • max - Maximum player count for the period
    • average - Average player count for the period
    • min - Minimum player count for the period
    • peak_hour - Hour with most players (0-23)
    • members_max, members_average, members_min - For Discord servers: member statistics (null for other servers)
    • timestamp - ISO 8601 format (only for 15min granularity)

2. Server Map Statistics

Get server map usage statistics over a specified time period.

Endpoint:

GET /api/servers/{server}/stats/maps

Parameters:

Parameter Type Required Default Description
server integer Yes - Server ID (route parameter)
days integer No 14 Number of days to retrieve statistics for (1-365)

Examples:

# Last 14 days map statistics
GET /api/servers/1/stats/maps?days=14

# Last 7 days map statistics
GET /api/servers/1/stats/maps?days=7

# Last 24 hours map statistics
GET /api/servers/1/stats/maps?days=1

Response Format:

When days > 1:

{
  "server_id": 1,
  "range": {
    "from": "2025-11-01",
    "to": "2025-11-15",
    "days": 14
  },
  "granularity": "day",
  "maps": [
    {
      "map": "de_dust2",
      "plays": 245,
      "average_percentage": 45.5
    },
    {
      "map": "de_mirage",
      "plays": 180,
      "average_percentage": 33.3
    },
    {
      "map": "de_inferno",
      "plays": 112,
      "average_percentage": 21.2
    }
  ]
}

When days = 1:

{
  "server_id": 1,
  "range": {
    "from": "2025-11-15 00:00:00",
    "to": "2025-11-15 23:59:59",
    "days": 1
  },
  "granularity": "hour",
  "maps": [
    {
      "map": "de_dust2",
      "plays": 12,
      "average_percentage": 50.0
    },
    {
      "map": "de_mirage",
      "plays": 8,
      "average_percentage": 33.3
    }
  ]
}

Field Descriptions:

  • server_id - Server ID
  • range.from - Start date/time
  • range.to - End date/time
  • range.days - Number of days
  • granularity - Data granularity (day or hour)
  • maps - Map statistics array, sorted by plays in descending order
    • map - Map name
    • plays - Number of times the map was played during the period
    • average_percentage - Average percentage of time the map was played

3. Server Player Heatmap Statistics

Get server player heatmap statistics (hours per day format).

Endpoint:

GET /api/servers/{server}/stats/heatmap

Parameters:

Parameter Type Required Default Description
server integer Yes - Server ID (route parameter)
days integer No 14 Number of days to retrieve statistics for (1-365)

Examples:

# Last 7 days heatmap statistics
GET /api/servers/1/stats/heatmap?days=7

# Last 14 days heatmap statistics
GET /api/servers/1/stats/heatmap?days=14

# Last 30 days heatmap statistics
GET /api/servers/1/stats/heatmap?days=30

Response Format:

{
  "server_id": 1,
  "range": {
    "from": "2025-11-08",
    "to": "2025-11-15",
    "days": 7
  },
  "granularity": "hour",
  "heatmap": {
    "2025-11-08": {
      "0": {
        "average": 15,
        "max": 20,
        "samples": 4,
        "map": null
      },
      "1": {
        "average": 12,
        "max": 18,
        "samples": 4,
        "map": null
      },
      "12": {
        "average": 35,
        "max": 45,
        "samples": 4,
        "map": null
      },
      "20": {
        "average": 48,
        "max": 50,
        "samples": 4,
        "map": null
      }
    },
    "2025-11-09": {
      "0": {
        "average": 18,
        "max": 22,
        "samples": 4,
        "map": null
      }
    }
  },
  "daily_peak": {
    "2025-11-08": 50,
    "2025-11-09": 48,
    "2025-11-10": 52
  }
}

Field Descriptions:

  • server_id - Server ID
  • range.from - Start date
  • range.to - End date
  • range.days - Number of days
  • granularity - Always hour
  • heatmap - Object with dates as keys (YYYY-MM-DD format)
    • Each date object has hours as keys (0-23)
    • Each hour has:
      • average - Average player count per hour
      • max - Maximum player count per hour
      • samples - Number of samples collected per hour
      • map - Map name (currently always null)
  • daily_peak - Object with date as key and maximum player count per day as value

Authenticated Endpoints (API v1)

These endpoints require API token authentication. Use them in your applications with your API token.

5. Server List

Get a list of servers with filtering and sorting options.

Endpoint:

GET /api/v1/servers

Authentication: Requires API token

Parameters:

Parameter Type Required Default Description
user_servers_only boolean No true Show only user's servers
server_ids string No - Comma-separated server IDs (e.g., "1,2,3")
search string No - Search by hostname or description
status string No - Server status: online, offline
is_vip boolean No - Show only VIP servers
game_type_id integer No - Filter by game type
category_id integer No - Filter by category
country_code string No - Filter by country code
sort string No created_at Sorting: created_at, current_players, votes_count
order string No desc Sort order: asc, desc
page integer No 1 Page number
per_page integer No 15 Results per page (max 100)

Examples:

# Get all user's servers
curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/servers"

# Get all servers (not just user's)
curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/servers?user_servers_only=false"

# Search and filtering
curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/servers?search=zombie&status=online&is_vip=true"

# Specific servers by ID
curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/servers?server_ids=1,2,3"

Response Format:

{
  "data": [
    {
      "id": 1,
      "hostname": "My Server",
      "description": "Server description",
      "ip": "192.168.1.1",
      "port": 27015,
      "display_address": "192.168.1.1:27015",
      "status": "online",
      "current_players": 25,
      "max_players": 32,
      "current_map": "de_dust2",
      "is_vip": false,
      "game_type": {
        "id": 1,
        "name": "Counter-Strike 1.6",
        "slug": "cs16"
      },
      "categories": [
        {
          "id": 1,
          "name": "Zombie",
          "slug": "zombie"
        }
      ],
      "votes_count": 42,
      "url": "https://list2play.com/servers/cs16/my-server"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 75
  },
  "meta": {
    "game_types": [
      {
        "id": 1,
        "name": "Counter-Strike 1.6",
        "slug": "cs16"
      }
    ],
    "categories": [
      {
        "id": 1,
        "name": "Zombie",
        "slug": "zombie"
      }
    ],
    "user_servers_only": true
  }
}

6. Meta Information - Game Types

Get a list of all available game types.

Endpoint:

GET /api/v1/meta/game-types

Authentication: Requires API token

Response Format:

{
  "data": [
    {
      "id": 1,
      "name": "Counter-Strike 1.6",
      "slug": "cs16"
    },
    {
      "id": 2,
      "name": "Minecraft",
      "slug": "minecraft"
    }
  ]
}

7. Meta Information - Categories

Get a list of all available categories.

Endpoint:

GET /api/v1/meta/categories

Authentication: Requires API token

Response Format:

{
  "data": [
    {
      "id": 1,
      "name": "Zombie",
      "slug": "zombie"
    },
    {
      "id": 2,
      "name": "Surf",
      "slug": "surf"
    }
  ]
}

8. Meta Information - Countries

Get a list of all country codes where servers exist.

Endpoint:

GET /api/v1/meta/countries

Authentication: Requires API token

Response Format:

{
  "data": [
    "US",
    "GB",
    "DE",
    "FR"
  ]
}

9. Server Details

Get detailed information about a specific server.

Endpoint:

GET /api/v1/servers/{server}

Authentication: Requires API token

Parameters:

Parameter Type Required Description
server integer Yes Server ID (route parameter)

Example:

curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/servers/1"

Response Format:

{
  "id": 1,
  "slug": "my-server",
  "hostname": "My Server",
  "description": "Server description",
  "ip": "192.168.1.1",
  "dns_name": null,
  "port": 27015,
  "query_port": 27015,
  "display_address": "192.168.1.1:27015",
  "country_code": "US",
  "status": "online",
  "current_players": 25,
  "max_players": 32,
  "bot_players": 0,
  "current_map": "de_dust2",
  "is_vip": false,
  "vip_expires_at": null,
  "join_url": "steam://connect/192.168.1.1:27015",
  "discord_invite_code": null,
  "discord_invite_url": null,
  "first_seen_at": "2025-01-01T00:00:00+00:00",
  "last_checked_at": "2025-12-06T12:00:00+00:00",
  "last_online_at": "2025-12-06T12:00:00+00:00",
  "game_type": {
    "id": 1,
    "name": "Counter-Strike 1.6",
    "slug": "cs16"
  },
  "categories": [
    {
      "id": 1,
      "name": "Zombie",
      "slug": "zombie"
    }
  ]
}

10. Server Votes

Get server vote information.

Endpoint:

GET /api/v1/servers/{server}/votes

Authentication: Requires API token

Parameters:

Parameter Type Required Description
server integer Yes Server ID (route parameter)

Example:

curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/servers/1/votes"

Response Format:

{
  "server_id": 1,
  "total_votes": 42,
  "votes_today": 5,
  "votes_this_week": 15,
  "votes_this_month": 30
}

11. User Information

Get authenticated user information.

Endpoint:

GET /api/user

Authentication: Requires Sanctum token

Response Format:

{
  "id": 1,
  "name": "User Name",
  "email": "[email protected]",
  ...
}

Error Handling

The API returns standard HTTP status codes:

  • 200 OK - Request successful
  • 404 Not Found - Server not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Error Response Format:

{
  "message": "Error message",
  "error": "Additional error information"
}

Finding Server ID

You can find the server ID in several ways:

  1. Go to the server page: https://list2play.com/servers/{game}/{slug}
  2. Open the page source or use developer tools
  3. The server ID is used internally in the system

Or use the API endpoint /api/v1/servers with search to find the server ID by hostname or slug.

Examples using cURL

Public Endpoints (no authentication)

# Get player statistics
curl "https://list2play.com/api/servers/1/stats/players?days=14"

# Get map statistics
curl "https://list2play.com/api/servers/1/stats/maps?days=7"

# Get heatmap statistics
curl "https://list2play.com/api/servers/1/stats/heatmap?days=7"

Authenticated Endpoints (require token)

# Get server list
curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/servers"

# Get game types
curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/meta/game-types"

# Get server details
curl -H "Authorization: YOUR_TOKEN" "https://list2play.com/api/v1/servers/1"

Examples using JavaScript (Fetch API)

Public Endpoints (no authentication)

// Get player statistics
fetch('https://list2play.com/api/servers/1/stats/players?days=14')
  .then(response => response.json())
  .then(data => {
    console.log('Player statistics:', data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

// Get map statistics
fetch('https://list2play.com/api/servers/1/stats/maps?days=7')
  .then(response => response.json())
  .then(data => {
    console.log('Map statistics:', data);
  });

// Get heatmap statistics
fetch('https://list2play.com/api/servers/1/stats/heatmap?days=7')
  .then(response => response.json())
  .then(data => {
    console.log('Heatmap statistics:', data);
  });

Authenticated Endpoints (require token)

const API_TOKEN = 'YOUR_TOKEN';
const API_BASE = 'https://list2play.com/api/v1';

// Get server list
fetch(`${API_BASE}/servers`, {
  headers: {
    'Authorization': API_TOKEN
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Servers:', data);
  });

// Get game types
fetch(`${API_BASE}/meta/game-types`, {
  headers: {
    'Authorization': API_TOKEN
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Game types:', data);
  });

// Get server details
fetch(`${API_BASE}/servers/1`, {
  headers: {
    'Authorization': API_TOKEN
  }
})
  .then(response => response.json())
  .then(data => {
    console.log('Server details:', data);
  });

Notes

  1. Data Updates: Statistics are updated every 5 minutes with a graceful backoff mechanism for unreachable servers.

  2. Discord Servers: For Discord servers, members_max, members_average, and members_min fields will be filled with member statistics. For other servers, these fields will be null.

  3. Empty Results: If a server has no statistics data for the selected time period, series or maps arrays will be empty.

  4. Granularity:

    • When days = 1, 15min granularity is used for player statistics
    • When days > 1, day granularity is used
    • Heatmap always uses hour granularity

  5. Date Format:

    • Daily granularity uses YYYY-MM-DD format
    • 15min granularity uses ISO 8601 format with timezone

Version

Documentation corresponds to the API version in use as of December 2025.

Support

If you have questions or encounter issues with the API, please contact our support team: [email protected]

Need help with this topic?

Reach out if you have questions about the latest List2Play improvements.

Contact support

Related articles

Nov 12, 2025

List2Play Refund & Payment Policy

Understand how List2Play handles successful payments, failed checkouts, refunds, and chargebacks.

Nov 12, 2025

List2Play Cookie Policy

This policy explains essential, analytics, and optional cookies used on List2Play, plus your choices for controlling the...

Nov 12, 2025

Support & Contact

Need help? This page lists every support channel, response time, and what details to include in your message.