v1.0REST APIInteractive

API Documentation

Access FiveM server statistics, resource data, and leaderboards programmatically. Free to use with rate limiting. Click "Try it" on any endpoint to test live.

Base URL
/api/v1
Rate Limit (Public)
60 requests/minute
Rate Limit (API Key)
300 requests/minute

Authentication

The API can be used without authentication with a rate limit of 60 requests per minute. For higher limits, include your API key in the Authorization header.

With API Key

curl -H "Authorization: Bearer sm_live_your_api_key_here" \
  https://metrics.swisser.dev/api/v1/stats

Rate Limit Headers

All responses include rate limit information in headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1702234567890

Global Stats

GET/api/v1/stats

Get global statistics about servers, players, and resources.

Query Parameters

gamestringFilter by game: "gta5" or "rdr3"
Request
curl "https://metrics.swisser.dev/api/v1/stats?game=gta5"
Response
{
  "success": true,
  "data": {
    "totalServers": 12543,
    "onlineServers": 8721,
    "totalPlayers": 156432,
    "totalResources": 45231,
    "avgPlayersPerServer": 18,
    "lastUpdated": "2024-12-10T15:30:00.000Z"
  },
  "timestamp": "2024-12-10T15:30:00.000Z"
}

Server List

GET/api/v1/servers

Get a paginated list of servers with filtering and sorting options.

Query Parameters

pagenumberPage number (default: 1)
limitnumberResults per page, max 100 (default: 50)
searchstringSearch by hostname or endpoint
localestringFilter by locale (e.g., "de-DE", "en-US")
gamestringFilter by game: "gta5" or "rdr3"
sortstring"players", "name", or "upvotes"
orderstring"asc" or "desc" (default: "desc")
Request
curl "https://metrics.swisser.dev/api/v1/servers?page=1&limit=10&locale=de-DE"
Response
{
  "success": true,
  "data": [
    {
      "id": 1234,
      "endpoint": "123.45.67.89:30120",
      "hostname": "My Awesome Server",
      "hostnameClean": "my awesome server",
      "locale": "de-DE",
      "players": 128,
      "maxClients": 256,
      "gamename": "gta5",
      "premium": "pt",
      "banner": "https://...",
      "upvotePower": 42,
      "isOffline": false
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1234,
    "totalPages": 124
  },
  "timestamp": "2024-12-10T15:30:00.000Z"
}

Server Detail

GET/api/v1/servers/{endpoint}

Get detailed information about a specific server including resources and player stats.

Query Parameters

endpointstringrequiredServer endpoint (e.g., 123.45.67.89:30120)
Request
curl "https://metrics.swisser.dev/api/v1/servers/123.45.67.89%3A30120"
Response
{
  "success": true,
  "data": {
    "id": 1234,
    "endpoint": "123.45.67.89:30120",
    "hostname": "My Awesome Server",
    "players": 128,
    "maxClients": 256,
    "gamename": "gta5",
    "gametype": "roleplay",
    "mapname": "los santos",
    "projectName": "My RP Project",
    "projectDesc": "The best RP server...",
    "onesync": true,
    "serverVersion": "7290",
    "firstSeen": "2024-01-15T10:00:00.000Z",
    "lastSeen": "2024-12-10T15:30:00.000Z",
    "stats": {
      "avgPlayers": 95,
      "maxPlayers": 180,
      "minPlayers": 12
    },
    "resources": [
      { "id": 1, "name": "es_extended", "category": "framework" },
      { "id": 2, "name": "esx_identity", "category": "script" }
    ]
  },
  "timestamp": "2024-12-10T15:30:00.000Z"
}

Resource List

GET/api/v1/resources

Get a paginated list of resources with filtering and sorting options.

Query Parameters

pagenumberPage number (default: 1)
limitnumberResults per page, max 100 (default: 50)
searchstringSearch by resource name
categorystringFilter by category
prefixstringFilter by name prefix (e.g., "esx_")
suffixstringFilter by name suffix
sortstring"serverCount", "totalPlayers", "name", or "firstSeen"
orderstring"asc" or "desc" (default: "desc")
Request
curl "https://metrics.swisser.dev/api/v1/resources?prefix=esx_&sort=serverCount"
Response
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "es_extended",
      "category": "framework",
      "firstSeen": "2023-01-01T00:00:00.000Z",
      "serverCount": 4521,
      "onlineServerCount": 3210,
      "totalPlayers": 89432
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 45231,
    "totalPages": 905
  },
  "timestamp": "2024-12-10T15:30:00.000Z"
}

Resource Detail

GET/api/v1/resources/{name}

Get detailed information about a specific resource including rankings.

Query Parameters

namestringrequiredResource name (e.g., es_extended)
Request
curl "https://metrics.swisser.dev/api/v1/resources/es_extended"
Response
{
  "success": true,
  "data": {
    "id": 1,
    "name": "es_extended",
    "category": "framework",
    "firstSeen": "2023-01-01T00:00:00.000Z",
    "serverCount": 4521,
    "onlineServerCount": 3210,
    "totalPlayers": 89432,
    "serverRank": 1,
    "playerRank": 1,
    "serverRankChange": 0,
    "playerRankChange": 2
  },
  "timestamp": "2024-12-10T15:30:00.000Z"
}

Leaderboard

GET/api/v1/leaderboard

Get a ranked leaderboard of servers or resources.

Query Parameters

typestringrequired"resources" or "servers"
pagenumberPage number (default: 1)
limitnumberResults per page, max 100 (default: 50)
sortstring"players" or "servers" (for resources)
searchstringSearch filter
prefixstringName prefix filter (resources only)
suffixstringName suffix filter (resources only)
gamestringGame filter: "gta5" or "rdr3"
localestringLocale filter (servers only)
Request
curl "https://metrics.swisser.dev/api/v1/leaderboard?type=resources&sort=servers&limit=10"
Response
{
  "success": true,
  "data": [
    {
      "rank": 1,
      "id": 1,
      "name": "es_extended",
      "category": "framework",
      "serverCount": 4521,
      "onlineServerCount": 3210,
      "totalPlayers": 89432,
      "rankChange": 0
    },
    {
      "rank": 2,
      "id": 2,
      "name": "qb-core",
      "category": "framework",
      "serverCount": 3892,
      "onlineServerCount": 2891,
      "totalPlayers": 76543,
      "rankChange": 1
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 45231,
    "totalPages": 4524
  },
  "timestamp": "2024-12-10T15:30:00.000Z"
}

Error Responses

All error responses follow a consistent format with appropriate HTTP status codes.

400Bad Request
{
  "success": false,
  "data": null,
  "error": "Invalid parameter: page must be a number",
  "timestamp": "2024-12-10T15:30:00.000Z"
}
401Unauthorized
{
  "success": false,
  "data": null,
  "error": "Invalid API key",
  "timestamp": "2024-12-10T15:30:00.000Z"
}
404Not Found
{
  "success": false,
  "data": null,
  "error": "Server not found",
  "timestamp": "2024-12-10T15:30:00.000Z"
}
429Rate Limited
{
  "success": false,
  "data": null,
  "error": "Rate limit exceeded. Please try again later.",
  "timestamp": "2024-12-10T15:30:00.000Z"
}

Code Examples

TypeScript / JavaScript

Using fetch with TypeScript types

interface ApiResponse<T> {
  success: boolean;
  data: T | null;
  error?: string;
  meta?: { page: number; limit: number; total: number; totalPages: number };
  timestamp: string;
}

interface Server {
  id: number;
  endpoint: string;
  hostname: string;
  players: number;
  maxClients: number;
  // ... more fields
}

async function getServers(options: { page?: number; limit?: number } = {}) {
  const params = new URLSearchParams();
  if (options.page) params.set('page', String(options.page));
  if (options.limit) params.set('limit', String(options.limit));

  const response = await fetch(
    `https://metrics.swisser.dev/api/v1/servers?${params}`,
    {
      headers: {
        'Authorization': 'Bearer sm_live_your_api_key', // optional
      },
    }
  );

  const data: ApiResponse<Server[]> = await response.json();

  if (!data.success) {
    throw new Error(data.error || 'API request failed');
  }

  return data;
}

// Usage
const { data: servers, meta } = await getServers({ page: 1, limit: 10 });
console.log(`Found ${meta?.total} servers`);

Python

Using requests library

import requests

API_BASE = "https://metrics.swisser.dev/api/v1"
API_KEY = "sm_live_your_api_key"  # optional

def get_servers(page=1, limit=50, locale=None):
    params = {"page": page, "limit": limit}
    if locale:
        params["locale"] = locale

    headers = {}
    if API_KEY:
        headers["Authorization"] = f"Bearer {API_KEY}"

    response = requests.get(f"{API_BASE}/servers", params=params, headers=headers)
    data = response.json()

    if not data["success"]:
        raise Exception(data.get("error", "API request failed"))

    return data

# Usage
result = get_servers(page=1, limit=10, locale="de-DE")
print(f"Found {result['meta']['total']} servers")

for server in result["data"]:
    print(f"{server['hostname']}: {server['players']} players")

Need an API Key?

Contact us to get access to higher rate limits for your project.

Contact Us