Data Freshness
How probing, updater metadata, staleness and auto-insert interact.
The API never queries a game server while you wait. Workers probe tracked servers on a schedule and the API serves what they last stored. Everything below exists so a client can tell how old that state is.
The lifecycle of an address
- You ask for a
game_id + ip:portpair the platform has not seen. - If both parts are valid, the pair is registered and listed in
_meta.inserted_servers. Its value in this response is{"message": "Server not updated yet, or not existing in database"}. - A worker picks it up and probes it.
- Later requests return the full payload.
The first response for a new address is therefore empty by design. Poll again after about a minute instead of treating it as a failure.
_updater
Every address that exists in the database carries probe metadata:
"_updater": {
"status": "online",
"firewall_interval_minutes": 1,
"firewall_label": "none",
"next_probe_at": "2026-08-30T13:23:00.000Z",
"last_probe_at": "2026-08-30T13:22:36.000Z",
"last_online_at": "2026-08-30T13:22:36.000Z"
}| Field | Meaning |
|---|---|
status | Last known state of the server: online, unknown, or another operational state. |
firewall_interval_minutes | Minutes between probes for this server. Rises when a server stops answering. |
firewall_label | Human-readable form of that interval, none at the default rate. |
next_probe_at | When the next probe is due, ISO 8601 UTC. |
last_probe_at | When it was last probed, whatever the outcome. |
last_online_at | The last time it actually answered. |
These timestamps are ISO 8601. The updated field inside the payload is not: it
is YYYY-MM-DD HH:MM:SS in UTC. Parsing it as local time is the single most
common integration bug against this API.
A server that stops answering is probed less often rather than dropped, so
firewall_interval_minutes grows and last_online_at stops advancing. Use
last_online_at, not the absence of data, to decide a server is gone.
Staleness
A payload older than its expected refresh window is still returned, marked:
{
"message": "Server data is stale and awaiting a fresh updater refresh",
"_stale": true,
"_stale_age_seconds": 4705,
"_stale_expected_max_age_seconds": 180
}The baseline window is 180 seconds. For a server currently online, the
window widens to that server's own probe interval plus a small grace period, so a
server deliberately probed every 5 minutes is not reported as stale at 4 minutes.
Recommended handling:
_staleabsent: current data, show it plainly._stale: true: show the values with a "last seen" timestamp fromupdated. The fields are all still there.messagepresent with no other fields: nothing has been collected yet.
Discarding stale payloads throws away the only data you have. Label it instead.
Caching on your side
- The game catalogue is stable. Cache it for hours, not seconds.
- Server payloads refresh no faster than the probe interval, so polling
/v1/post/fetchmore often than once a minute per server returns the same bytes and spends quota. Batch many addresses into one request instead of polling one address frequently.