API

Aktualny stan wszystkich śledzonych serwerów plus suma zbiorcza. Dane pochodzą z pamięci podręcznej odświeżanej co POLL_INTERVAL_MS (domyślnie 20 s), więc odpytywanie częściej niż co 20 s nic nie wnosi.

curl https://stats.bykens.eu/api/stats

{
  "servers": [
    {
      "code": "okz5dj",
      "label": "Intouch.gg",
      "hostname": "INTOUCH",
      "banner": "https://cdn-intouch.realmgaming.eu/baner.png",
      "players": 121,
      "max": 230,
      "queue": 2,
      "upvotes": 0,
      "framework": "ESX",
      "resourceCount": 412,
      "updatedAt": "2026-09-14T11:29:10.380Z",
      "trend":     { "players": "flat", "queue": "flat" },
      "peakToday": { "players": 121, "queue": 2 },
      "uptime": {
        "day":  { "percent": 100, "checks": 288 },
        "week": { "percent": 99.4, "checks": 2016 }
      },
      "health": {
        "grade": "A",
        "powody": [],
        "decyduje": "uptime",
        "uptime":   { "znany": true, "powod": null, "percent": 99.4, "checks": 2016, "hours": 168, "band": "ponad-99" },
        "wskaznik": { "znany": true, "powod": null, "status": "brak-wzorca", "rodzinyPotwierdzone": [], "rodzinyObserwowane": [], "observations": 41 }
      }
    }
  ],
  "totals": { "players": 246, "max": 931, "queue": 2 },
  "generatedAt": "2026-09-14T11:29:21.793Z"
}

Trwała oś czasu zdarzeń: awaria, powrót, rekord dnia, prawie pełny. Okno 90 dni, najnowsze pierwsze. To samo, co pokazuje strona Historia.

{
  "wpisy": [
    { "id": 812, "at": "2026-09-18T09:14:02.118Z", "type": "offline", "code": "lerb6bv", "label": "Intouch.gg", "value": null }
  ],
  "razem": 137,
  "offset": 0,
  "limit": 50,
  "przeglad": {
    "serwery": [{ "code": "lerb6bv", "label": "Intouch.gg", "ile": 41 }],
    "typy":    [{ "type": "offline", "ile": 22 }],
    "razem": 137,
    "najstarszy": "2026-06-21T18:02:11.004Z",
    "oknoDni": 90,
    "sufit": 10000
  }
}

Historia sumy wszystkich serwerów — próbka co HISTORY_INTERVAL_MS (domyślnie 5 min), maksymalnie 288 próbek, czyli pełne 24 h. Z parametrem ?code= zwraca historię jednego serwera (samą tablicę, bez intervalMs).

curl https://stats.bykens.eu/api/history
curl https://stats.bykens.eu/api/history?code=okz5dj

{
  "totals": [
    { "timestamp": "2026-09-14T11:29:10.381Z", "players": 246, "max": 931, "queue": 2 }
  ],
  "intervalMs": 300000
}

Heatmapa godzin szczytu: 168 komórek (7 dni tygodnia × 24 godziny) ze średnią liczbą graczy i kolejki. Narasta przez cały czas życia serwisu, więc im dłużej chodzi, tym wiarygodniejsza. Komórki bez próbek zwracają null, a nie zero — to celowe rozróżnienie „brak danych" od „zero graczy".

curl https://stats.bykens.eu/api/hourly

{
  "cells": [
    { "day": 0, "hour": 0,  "players": null, "queue": null, "samples": 0 },
    { "day": 1, "hour": 13, "players": 246,  "queue": 2,    "samples": 12 }
  ],
  "days": 1,
  "since": "2026-09-14",
  "intervalMs": 300000
}

Ostatnie ~20 zdarzeń (serwer padł, wrócił, zapełnił się, pobił rekord), najnowsze pierwsze. Żyją wyłącznie w pamięci — restart usługi czyści listę i tak ma być: to podgląd ostatnich minut, nie dziennik zdarzeń.

curl https://stats.bykens.eu/api/events

{
  "events": [
    { "id": 7, "at": "2026-09-14T11:31:02.118Z", "type": "record",
      "code": "okz5dj", "label": "Intouch.gg", "value": 231 }
  ]
}

Wszystkie serwery dodane przez odwiedzających, z kompletem danych wyciągniętych z API FiveM. Czyta wyłącznie z pamięci podręcznej — Twoje żądanie nigdy nie wywoła zapytania do cfx.

curl https://stats.bykens.eu/api/lookup/servers

{
  "servers": [
    {
      "code": "yokb5k",
      "hostname": "Realm Roleplay | WL-OFF",
      "projectName": "RealmRP", "projectDesc": "Polski serwer roleplay",
      "players": 50, "max": 500, "queue": 0, "peakPlayers": 297,
      "framework": null, "resourceCount": 324,
      "locale": "pl-PL", "tags": ["roleplay", "wl-off"],
      "gameName": null, "whitelist": false, "whitelistInfo": null,
      "oneSync": "on", "gameBuild": "3570", "scriptHook": false,
      "pureLevel": null,
      "discord": "https://dc.realmrp.pl", "store": "https://sklep.realmrp.pl",
      "playerNames": { "total": 226, "anonymized": true },
      "endpoints": ["https://30123-spillway.example.eu/"],
      "endpointsHidden": false, "private": false,
      "online": true, "error": null,
      "joinUrl": "https://cfx.re/join/yokb5k"
    }
  ],
  "count": 1,
  "limit": 300,
  "batchMax": 10,
  "intervalMs": 60000,
  "clientRefreshMs": 15000
}

Jeden serwer, pełne rozliczenie wskaźnika licznika graczy — to, co pokazuje strona /serwer?server=KOD, otwierana kliknięciem w nazwę serwera na dashboardzie albo na liście. Jedyne miejsce, w którym obie ścieżki wskaźnika spotykają się w jednej odpowiedzi (activityReport z bieżących odczytów i patternReport z dobowych rollupów), i jedyne, które oddaje pomiary bez progów.

Dlaczego osobno od /api/lookup/servers: ten endpoint oddaje współczynnik zmienności i długość zastoju także wtedy, gdy nie sięgają progu. W hurtowej odpowiedzi listy ta sama liczba jechałaby dla trzystu serwerów przy każdym odświeżeniu każdej otwartej karty. Tutaj pojawia się wyłącznie wtedy, gdy ktoś świadomie otworzył stronę jednego serwera.

curl "https://stats.bykens.eu/api/serwer?server=okz5dj"

{
  "code": "okz5dj", "pinned": true, "online": true,
  "hostname": "INTOUCH", "players": 235, "max": 249, "queue": 2,
  "lastSeen": "2026-09-15T22:39:09.694985519Z",
  "observedAtMs": 1789511949694,
  "checkedAt": "2026-09-15T22:42:57.069Z",

  "counters": { "state": "zgodne", "reported": 246, "counted": 235,
                "diff": 11, "direction": "zawyzanie", "percent": 5,
                "percentOf": "counted", "countedZero": false },
  "countersThresholds": { "minPercent": 25, "minPlayers": 10 },

  "activityReport": { "status": "brak-wzorca", "level": "brak",
                      "families": [], "confirmedFamilies": [], "signals": [],
                      "quality": { "observations": 26, "spanMinutes": 118, "grade": "pelna" },
                      "dataQuality": { "basis": "okno-obserwacji",
                        "coverage": { "percent": 100, "bucketMinutes": 10,
                                      "bucketsWithObservation": 11, "bucketsTotal": 11,
                                      "spanMinutes": 118, "observations": 26,
                                      "minObservations": 12, "minSpanMinutes": 90 },
                        "largestGap": { "minutes": 7, "maxAllowedMinutes": 29, "includesNow": false },
                        "age": { "sourceObservationSeconds": 212, "sinceLastReadingSeconds": 14,
                                 "staleAfterMinutes": 15, "freshness": "swieze" },
                        "sourceRepeats": 7, "grade": "pelna", "limits": [] } },

  "measurements": {
    "window": { "observations": 26, "spanMinutes": 118, "maxGapMinutes": 7,
                "sufficient": true, "minObservations": 12, "minSpanMinutes": 90,
                "maxGapShare": 0.25, "bufferWindowHours": 6, "samplesMax": 180,
                "staleAfterMinutes": 15 },
    "variation": { "computable": true, "reason": null, "meets": false,
                   "cvPercent": 4.7, "threshold": 2, "baseThreshold": 2, "mean": 231,
                   "minMeanPlayers": 20, "observations": 26, "minutes": 118,
                   "capacityBand": "z-zapasem", "capacitySharePercent": 46,
                   "capacityToleranceSlots": 25, "strictness": 1 },
    "stall":     { "computable": true, "reason": null, "meets": false,
                   "players": 235, "minutes": 5, "typicalMinutes": 9, "changes": 12,
                   "requiredMinutes": 60, "minMinutes": 60, "factor": 6,
                   "baseMinMinutes": 60, "baseFactor": 6,
                   "minChanges": 3, "minPlayers": 20, "atCapacity": false,
                   "capacityBand": "z-zapasem", "capacitySharePercent": 47,
                   "capacityToleranceSlots": 25, "strictness": 1 },
    "families": {
      "malaZmiennosc":    { "met": false, "confirmed": false, "forMinutes": null,
                            "observations": 0, "missingForMinutes": 118,
                            "releaseInMinutes": null,
                            "wasConfirmed": true, "timesConfirmed": 1,
                            "sinceReleasedMinutes": 98, "confirmMinutes": 45,
                            "confirmMinObservations": 6, "releaseMinutes": 20 },
      "rozjazdLicznikow": { "met": false, "confirmed": false, "...": "jak wyżej" }
    }
  },

  "availability": { "hourlyProfile": false, "hourlyProfileReason": "tylko-przypiete" },

  "patternReport": { "status": "obserwacje", "level": "informacja", "...": "jak w /api/trends" },
  "daily": {
    "days": [
      { "date": "2026-09-05", "coveragePercent": 100, "avgPlayers": 100,
        "peakPlayers": 110, "hasProfile": true, "hoursCovered": 24,
        "hoursExpected": 24, "maxGapHours": 0, "ratio": 1.1,
        "used": true, "limited": false, "reason": null },
      { "date": "2026-09-08", "coveragePercent": 42, "avgPlayers": 100,
        "peakPlayers": 110, "hasProfile": true, "hoursCovered": 24,
        "hoursExpected": 24, "maxGapHours": 0, "ratio": null,
        "used": false, "limited": false, "reason": "pokrycie-doby" }
    ],
    "config": { "windowDays": 14, "minDays": 10, "minCoveragePercent": 90,
                "minHoursOf24": 22, "maxGapHours": 2, "ratioMax": 1.5,
                "minSharePercent": 80, "minMeanPlayers": 20 }
  },
  "generatedAt": "2026-09-16T00:42:57.201Z"
}

Porównanie tydzień do tygodnia dla każdego śledzonego serwera: średnia graczy, średnia kolejka i szczyty z ostatnich siedmiu pełnych dni wobec siedmiu poprzednich. Liczone z dziennych rollupów — zbioru całkowicie osobnego od /api/history (24 h) i /api/hourly (siatka 7×24 bez daty).

Dzisiejszy dzień nie wchodzi do żadnego okna — jest niepełny. Jeśli w oknie czternastu dni brakuje choć jednego, ten serwer dostaje ready: false i żadnych pól porównania: nie ma current, previous ani change. To celowe — liczba wyliczona z dziur wygląda tak samo jak prawdziwa.

curl https://stats.bykens.eu/api/trends

{
  "ready": true,
  "daysNeeded": 14,
  "weekDays": 7,
  "windows": {
    "current":  { "from": "2026-09-07", "to": "2026-09-13" },
    "previous": { "from": "2026-08-31", "to": "2026-09-06" }
  },
  "minSamplesPerDay": 144,
  "expectedSamplesPerDay": 288,
  "flatPercent": 5,
  "servers": [
    {
      "code": "okz5dj", "label": "Intouch.gg",
      "ready": true, "daysCollected": 31, "daysMissing": 0, "waitDays": 0,
      "current":  { "days": 7, "avgPlayers": 198.4, "avgQueue": 12.7, "peakPlayers": 250, "peakQueue": 61 },
      "previous": { "days": 7, "avgPlayers": 181.2, "avgQueue": 10.3, "peakPlayers": 248, "peakQueue": 54 },
      "change": {
        "players": { "comparable": true, "from": 181.2, "to": 198.4, "percent": 9,  "direction": "up" },
        "queue":   { "comparable": true, "from": 10.3,  "to": 12.7,  "percent": 23, "direction": "up" }
      }
    },
    {
      "code": "jjj4kl", "label": "Onbeat",
      "ready": false, "daysCollected": 11, "daysMissing": 3, "waitDays": 3,
      "pattern": null,
      "patternReport": {
        "status": "obserwacje",
        "level": "informacja",
        "families": ["ksztaltDoby"],
        "confirmedFamilies": [],
        "quality": { "days": 11, "limitedDays": 0, "daysWithProfile": 11, "minDays": 10, "grade": "pelna" },
        "signals": [
          { "id": "lowPeakToAverage", "family": "ksztaltDoby", "experimental": true, "confirmed": false,
            "data": { "days": 11, "lowDays": 11, "limitedDays": 0, "typicalRatio": 1.02,
                      "highestRatio": 1.05, "threshold": 1.5, "from": "2026-09-03", "to": "2026-09-13" } },
          { "id": "profileShape", "family": "ksztaltDoby", "experimental": true, "confirmed": false,
            "data": { "days": 11, "hours": 24, "profileAmplitude": 0.06, "profileAgreement": 0.31 } }
        ]
      }
    }
  ],
  "generatedAt": "2026-09-14T16:20:03.918Z"
}

Ranking najpopularniejszych resource'ów — na ilu ze śledzonych serwerów występuje każda nazwa. Liczony na żywo z pamięci procesu (dashboard plus lista serwerów, każdy serwer raz), z krótkim, kilkusekundowym oknem pamięci podręcznej. Nic tu nie jest zapisywane na dysk, więc to stan z tej chwili, a nie historia.

curl https://stats.bykens.eu/api/resources
curl "https://stats.bykens.eu/api/resources?limit=50&builtin=1"

{
  "top": [
    { "rank": 1, "name": "ox_lib",    "servers": 4, "percent": 100, "builtin": false },
    { "rank": 2, "name": "oxmysql",   "servers": 4, "percent": 100, "builtin": false },
    { "rank": 3, "name": "pma-voice", "servers": 4, "percent": 100, "builtin": false }
  ],
  "serversTotal": 5,
  "serversCounted": 4,
  "resourcesTotal": 883,
  "builtinTotal": 4,
  "builtinIncluded": false,
  "limit": 20,
  "generatedAt": "2026-09-14T16:02:11.004Z"
}

Dodaje serwer do wspólnej listy. Przyjmuje sam kod cfx.re albo pełny link (cfx.re/join/…, servers.fivem.net/servers/detail/…). Serwer musi istnieć — nieistniejący kod nie trafia na listę.

curl -X POST https://stats.bykens.eu/api/lookup/add \
  -H 'Content-Type: application/json' \
  -d '{"code":"okz5dj"}'

{ "ok": true, "code": "okz5dj", "added": true, "server": { … } }

Dodaje kilka serwerów jednym żądaniem. Pole codes to jeden kawałek tekstu — kod albo link na linię, albo oddzielone przecinkami; oba warianty działają zamiennie. Każda pozycja przechodzi dokładnie tę samą ścieżkę co przy /api/lookup/add: format kodu, deduplikacja, sufit długości listy i wymóg istnienia serwera.

curl -X POST https://stats.bykens.eu/api/lookup/add-many \
  -H 'Content-Type: application/json' \
  -d '{"codes":"okz5dj\njjj4kl, yokb5k"}'

{
  "ok": true,
  "results": [
    { "input": "okz5dj", "code": "okz5dj", "status": "added", "server": { … } },
    { "input": "jjj4kl", "code": "jjj4kl", "status": "already", "server": null },
    { "input": "abc!!!", "code": null,     "status": "bad_code", "server": null }
  ],
  "added": ["okz5dj"],
  "summary": { "added": 1, "already": 1, "bad_code": 1,
               "not_found": 0, "list_full": 0, "duplicate_in_batch": 0 },
  "count": 42,
  "limit": 300
}

Usuwa serwer z listy. Bez logowania — usunąć może każdy, tak samo jak każdy może dodać. Kod można podać w ciele żądania albo jako ?code=.

curl -X DELETE https://stats.bykens.eu/api/lookup/remove \
  -H 'Content-Type: application/json' \
  -d '{"code":"okz5dj"}'

{ "ok": true, "code": "okz5dj", "removed": true }

Ten sam ticker co /api/events, tyle że w formacie Atom — do wrzucenia w dowolny czytnik RSS. Strona główna ma <link rel="alternate" type="application/atom+xml">, więc czytniki znajdą kanał same po podaniu samego adresu serwisu.

curl https://stats.bykens.eu/feed.xml

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Statystyki serwerów FiveM — zdarzenia</title>
  <id>https://stats.bykens.eu/feed.xml</id>
  <link rel="self" type="application/atom+xml" href="https://stats.bykens.eu/feed.xml"/>
  <link rel="alternate" type="text/html" href="https://stats.bykens.eu/"/>
  <updated>2026-09-14T16:59:06.800Z</updated>
  <author><name>Statystyki serwerów FiveM</name></author>
  <entry>
    <title>Rekord kolejki: Intouch.gg (51)</title>
    <link rel="alternate" type="text/html" href="https://stats.bykens.eu/"/>
    <id>https://stats.bykens.eu/feed.xml#okz5dj-record-queue-2026-09-14T16:40:00.000Z</id>
    <updated>2026-09-14T16:40:00.000Z</updated>
    <published>2026-09-14T16:40:00.000Z</published>
    <category term="record-queue"/>
    <content type="text">Nowy dzisiejszy rekord kolejki na Intouch.gg: 51.</content>
  </entry>
</feed>

Dla zewnętrznych monitoringów (UptimeRobot i podobne). Bez logowania, z CORS-em, bez cache. Odpowiada na pytanie „czy ta usługa działa", a nie „czy serwery FiveM są online".

curl -i https://stats.bykens.eu/health

{
  "status": "ok",
  "uptimeSeconds": 9,
  "lastSuccessfulPollAt": "2026-09-14T14:14:07.393Z",
  "staleAfterSeconds": 60,
  "serversTracked": 3,
  "calibrationSampleSize": 0
}

Obrazek SVG z aktualną liczbą graczy — do wklejenia w README na GitHubie, na stronę serwera albo gdziekolwiek działa <img>. Generowany u nas, nie przez shields.io, więc nie zależy od obcej usługi. Wysyła Cache-Control: no-cache, żeby nie pokazywać liczby sprzed godzin, i Access-Control-Allow-Origin: *, żeby dało się go osadzić wszędzie.

![Gracze](https://stats.bykens.eu/badge.svg)
![Gracze](https://stats.bykens.eu/badge.svg?type=players)
![Kolejka](https://stats.bykens.eu/badge.svg?type=queue)
![Intouch](https://stats.bykens.eu/badge.svg?server=okz5dj)

<img src="https://stats.bykens.eu/badge.svg" alt="Gracze online" />

Dostępność serwera z ostatnich 24 h. Ta sama szata co /badge.svg, ale parametr server jest tu obowiązkowy — uptime liczymy per serwer i nie ma czegoś takiego jak „uptime sumy".

![Uptime](https://stats.bykens.eu/badge-uptime.svg?server=okz5dj)

Ocena zdrowia serwera — ta sama litera, którą liczy /api/stats i karta serwera. Odznaka nie pokazuje samej litery: obok niej stoi powód, bo ocena bez podstawy jest wyrokiem, a nie pomiarem. Parametr server obowiązkowy.

![Ocena](https://stats.bykens.eu/badge-ocena.svg?server=okz5dj)

Rozpoznany framework serwera — ESX, QBCore, Qbox, vRP, rg_core. Te same reguły wykrywania co na liście serwerów i w /api/stats, bo jest to jedna kopia w fivem-parse.js. Parametr server obowiązkowy.

![Framework](https://stats.bykens.eu/badge-framework.svg?server=okz5dj)

Nie API, tylko gotowa strona HTML do wstawienia w <iframe>: jedna karta, przezroczyste tło, bez nagłówka i sortowania. Bez parametru pokazuje sumę wszystkich śledzonych serwerów. Odświeża się sama co 15 s.

<iframe
  src="https://stats.bykens.eu/widget?server=okz5dj"
  width="330" height="160" style="border:0"
  title="Statystyki serwera FiveM" loading="lazy"></iframe>