Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerBridge/llms.txt

Use this file to discover all available pages before exploring further.

The /v2/tps endpoint returns the server’s ticks-per-second (TPS) measurements across four time windows plus the average tick duration in milliseconds. A healthy Minecraft server runs at 20 TPS; values below 20 indicate the server is struggling to keep up with the game loop. The implementation differs slightly between platforms but the response schema is identical on both.

​
Request

Method: GET
Path: /v2/tps

​
Headers

HeaderRequiredDescription
X-Auth-KeyYesAuthentication key from config.yaml → auth.key

​
Configuration

This endpoint can be disabled in config.yaml under v2-endpoints.tps. It is enabled by default. 
v2-endpoints:
  tps: true
If v2-endpoints.tps is set to false, the server returns a 403 Forbidden response.

​
Response

All numeric fields are double (64-bit floating point). A value of -1.0 indicates the metric is not yet available or could not be computed.
​
ok
boolean
required
Always true on success.
​
tps
number
required
Current TPS computed over approximately the last 20 ticks (roughly one second).
  • Fabric: Exponential moving average (EMA) with an alpha of 1/20, updated every tick.
  • Paper: First element of Bukkit.getServer().getTPS(), which is Paper’s own 1-second average.
​
tps_1m
number
required
TPS averaged over the last 1 minute.
  • Fabric: EMA with an alpha of 1/1200 (1200-tick / 60-second window).
  • Paper: Second element of Bukkit.getServer().getTPS() (Paper’s built-in 1-minute average). Returns -1.0 if the array has fewer than 2 elements.
​
tps_5m
number
required
TPS averaged over the last 5 minutes.
  • Fabric: EMA with an alpha of 1/6000 (6000-tick / 5-minute window).
  • Paper: Third element of Bukkit.getServer().getTPS() (Paper’s built-in 5-minute average). Returns -1.0 if the array has fewer than 3 elements.
​
tps_15m
number
required
TPS averaged over the last 15 minutes.
  • Fabric: Reuses the 5-minute EMA value (tps_5m), because Fabric does not expose a native 15-minute window.
  • Paper: Also reuses the 5-minute value (tps[2]), because Bukkit.getServer().getTPS() exposes only three values. Returns -1.0 if unavailable.
On both platforms tps_15m will equal tps_5m. The field is preserved in the schema for forward compatibility.
​
tick_time_ms
number
required
The average duration of a single server tick in milliseconds.
  • Fabric: Average of the last 100 tick durations recorded in nanoseconds, converted to milliseconds. Returns -1.0 if no samples are available yet.
  • Paper: Average of all values in Bukkit.getServer().getTickTimes() (nanoseconds), converted to milliseconds by dividing by 1,000,000. Returns -1.0 if the array is null or empty.
A healthy tick time is at or below 50 ms (the budget for one tick at 20 TPS).

​
Example Response

{
  "ok": true,
  "tps": 19.98,
  "tps_1m": 19.95,
  "tps_5m": 19.91,
  "tps_15m": 19.91,
  "tick_time_ms": 14.72
}

​
Example Response — Metrics Not Yet Available

{
  "ok": true,
  "tps": -1.0,
  "tps_1m": -1.0,
  "tps_5m": -1.0,
  "tps_15m": -1.0,
  "tick_time_ms": -1.0
}

​
Error Responses

Statuserror fieldCause
401unauthorizedMissing or incorrect X-Auth-Key header
403forbiddenEndpoint disabled via v2-endpoints.tps: false
405method_not_allowedRequest method was not GET
{
  "ok": false,
  "error": "unauthorized",
  "message": "Invalid X-Auth-Key"
}

​
curl Example

curl -s -X GET http://localhost:30007/v2/tps \
  -H "X-Auth-Key: your-auth-key"
On a freshly started server, the EMA windows may not have accumulated enough ticks to produce meaningful values. Fields will show -1.0 during this warm-up period. For the 5-minute and 15-minute windows on Fabric this can take several minutes of continuous uptime.
Because tps_15m mirrors tps_5m on both platforms, treat the 15-minute value as an approximate long-window indicator rather than a precise 15-minute measurement. Use GET /v2/info to detect the platform if your client needs to surface this distinction.

Build docs developers (and LLMs) love

Get started for freeTalk to us