Player Stats

All API requests require an X-API-Key header. Get your key from the Developer Dashboard.

curl -H "X-API-Key: sk_your_key_here" \
  "https://api.skytools.app/v1/..."

See Authentication for details on key formats and tier limits.

Player endpoints rely on an upstream bridge for UUID resolution. If it times out, the API may return stale cached data (up to 30 minutes old). Check meta.stale to detect this.

GET /v1/player/:username

Returns general Hypixel player stats including network level, karma, rank, achievement points, online status, and login timestamps. All fields are computed/derived from raw Hypixel data. Cache: 5 minutes

Path parameters

Parameter	Type	Description
`username`	string	Minecraft username (1-16 chars, alphanumeric and underscores only)

Examples

curl -H "X-API-Key: sk_your_key_here" \
  "https://api.skytools.app/v1/player/Technoblade"

const response = await fetch("https://api.skytools.app/v1/player/Technoblade", {
  headers: { "X-API-Key": "sk_your_key_here" },
});
const { data } = await response.json();
console.log(`${data.username} [${data.rankFormatted}] Level ${data.level}`);
console.log(`Online: ${data.online}`);

import requests

response = requests.get(
    "https://api.skytools.app/v1/player/Technoblade",
    headers={"X-API-Key": "sk_your_key_here"},
)
data = response.json()["data"]
print(f"{data['username']} [{data['rankFormatted']}] Level {data['level']}")

Response

{
  "success": true,
  "data": {
    "uuid": "b876ec32e396476ba1158438d83c67d4",
    "username": "Technoblade",
    "rank": "MVP_PLUS",
    "rankFormatted": "MVP+",
    "level": 256.72,
    "karma": 12500000,
    "achievementPoints": 8450,
    "questsCompleted": 1200,
    "challengesCompleted": 5000,
    "giftsGiven": 15,
    "ranksGiven": 3,
    "firstLogin": 1420070400000,
    "lastLogin": 1710600000000,
    "lastLogout": 1710590000000,
    "online": true,
    "totalExp": 84250000
  },
  "meta": { "cached": false, "api_version": "v1" }
}

Field	Type	Description
`uuid`	string	Player’s Minecraft UUID (dashless)
`username`	string	Player’s current username
`rank`	string	Resolved rank code (`MVP_PLUS`, `SUPERSTAR`, `NONE`, etc.)
`rankFormatted`	string	Human-readable rank name (`MVP+`, `MVP++`, `VIP`, `Default`, etc.)
`level`	number	Precise Hypixel network level (computed from XP)
`karma`	integer	Karma points
`achievementPoints`	integer	Total achievement points
`questsCompleted`	integer	Total quests completed (computed from achievements)
`challengesCompleted`	integer	Total challenges completed (computed from achievements)
`giftsGiven`	integer	Number of gifts given
`ranksGiven`	integer	Number of ranks gifted to other players
`firstLogin`	integer	First login timestamp (Unix ms)
`lastLogin`	integer	Last login timestamp (Unix ms)
`lastLogout`	integer	Last logout timestamp (Unix ms)
`online`	boolean	Whether the player is currently online (computed: `lastLogin > lastLogout`)
`totalExp`	integer	Raw network experience points

The rank field uses the Hypixel rank priority chain: rank > monthlyPackageRank > newPackageRank > packageRank. The rankFormatted field converts this to a human-readable name (e.g., SUPERSTAR becomes MVP++).

GET /v1/player/:username/bedwars

Returns BedWars stats with computed ratios, win rates, prestige tier, and per-mode breakdowns. Cache: 5 minutes

Path parameters

Parameter	Type	Description
`username`	string	Minecraft username

Example

curl -H "X-API-Key: sk_your_key_here" \
  "https://api.skytools.app/v1/player/Technoblade/bedwars"

Response

{
  "success": true,
  "data": {
    "uuid": "b876ec32e396476ba1158438d83c67d4",
    "username": "Technoblade",
    "level": 245,
    "prestige": "Stone",
    "coins": 850000,
    "overall": {
      "wins": 1200, "losses": 800,
      "winRate": 60.0, "wlr": 1.5,
      "kills": 5000, "deaths": 3000, "kdr": 1.67,
      "finalKills": 2500, "finalDeaths": 1000, "fkdr": 2.5,
      "bedsBroken": 1800, "bedsLost": 900, "bblr": 2.0,
      "winstreak": 5, "gamesPlayed": 2000
    },
    "modes": {
      "solo": { "wins": 300, "losses": 200, "winRate": 60.0, "wlr": 1.5, "kills": 1200, "deaths": 800, "kdr": 1.5, "finalKills": 600, "finalDeaths": 250, "fkdr": 2.4, "bedsBroken": 450, "bedsLost": 220, "bblr": 2.05, "winstreak": 2, "gamesPlayed": 500 },
      "doubles": { ... },
      "threes": { ... },
      "fours": { ... }
    }
  },
  "meta": { "cached": false, "api_version": "v1" }
}

Field	Type	Description
`level`	integer	BedWars star level (from achievements)
`prestige`	string	Computed prestige tier: `None`, `Stone`, `Iron`, `Gold`, `Diamond`, `Emerald`
`coins`	integer	BedWars coins
`*.wins`	integer	Games won
`*.losses`	integer	Games lost
`*.winRate`	number \| null	Win percentage (computed: `wins / gamesPlayed * 100`)
`*.wlr`	number \| null	Win/Loss ratio (computed)
`*.kills`	integer	Kills
`*.deaths`	integer	Deaths
`*.kdr`	number \| null	Kill/Death ratio (computed)
`*.finalKills`	integer	Final kills
`*.finalDeaths`	integer	Final deaths
`*.fkdr`	number \| null	Final Kill/Death ratio (computed)
`*.bedsBroken`	integer	Beds destroyed
`*.bedsLost`	integer	Beds lost
`*.bblr`	number \| null	Beds Broken/Lost ratio (computed)
`*.winstreak`	integer	Current winstreak
`*.gamesPlayed`	integer	Total games played (computed: `wins + losses`)

Ratios return null when the divisor is 0 (e.g., 0 deaths), or Infinity when the numerator is positive but the divisor is 0 (e.g., 5 wins, 0 losses). Modes: solo, doubles, threes, fours.

GET /v1/player/:username/skywars

Returns SkyWars stats with computed ratios, win rates, prestige tier, and per-mode breakdowns. Cache: 5 minutes

Path parameters

Parameter	Type	Description
`username`	string	Minecraft username

Example

curl -H "X-API-Key: sk_your_key_here" \
  "https://api.skytools.app/v1/player/Technoblade/skywars"

Response

{
  "success": true,
  "data": {
    "uuid": "b876ec32e396476ba1158438d83c67d4",
    "username": "Technoblade",
    "level": 18,
    "prestige": "Iron",
    "coins": 250000,
    "souls": 450,
    "overall": {
      "wins": 800, "losses": 600,
      "winRate": 57.14, "wlr": 1.33,
      "kills": 3000, "deaths": 2000, "assists": 500,
      "kdr": 1.5, "gamesPlayed": 1400
    },
    "modes": {
      "solo_normal": { "wins": 250, "losses": 180, "winRate": 58.14, "wlr": 1.39, "kills": 900, "deaths": 600, "kdr": 1.5, "gamesPlayed": 430 },
      "solo_insane": { ... },
      "team_normal": { ... },
      "team_insane": { ... }
    }
  },
  "meta": { "cached": false, "api_version": "v1" }
}

Field	Type	Description
`level`	integer	SkyWars level (computed from XP)
`prestige`	string	Computed prestige tier: `None`, `Stone`, `Iron`, `Gold`, `Rare`, `Epic`, `Legendary`, `Mythic`
`coins`	integer	SkyWars coins
`souls`	integer	SkyWars souls
`*.wins`	integer	Games won
`*.losses`	integer	Games lost
`*.winRate`	number \| null	Win percentage (computed: `wins / gamesPlayed * 100`)
`*.wlr`	number \| null	Win/Loss ratio (computed)
`*.kills`	integer	Kills
`*.deaths`	integer	Deaths
`*.assists`	integer	Assists (overall only)
`*.kdr`	number \| null	Kill/Death ratio (computed)
`*.gamesPlayed`	integer	Total games played (computed: `wins + losses`)

Modes: solo_normal, solo_insane, team_normal, team_insane.

GET /v1/player/:username/stats

Returns all game stats in one response: general info + BedWars + SkyWars combined. This is the most efficient way to get all player data in a single request. Cache: 5 minutes

Path parameters

Parameter	Type	Description
`username`	string	Minecraft username

Example

curl -H "X-API-Key: sk_your_key_here" \
  "https://api.skytools.app/v1/player/Technoblade/stats"

Response

{
  "success": true,
  "data": {
    "uuid": "b876ec32e396476ba1158438d83c67d4",
    "username": "Technoblade",
    "rank": "MVP_PLUS",
    "rankFormatted": "MVP+",
    "level": 256.72,
    "karma": 12500000,
    "achievementPoints": 8450,
    "questsCompleted": 1200,
    "challengesCompleted": 5000,
    "giftsGiven": 15,
    "ranksGiven": 3,
    "firstLogin": 1420070400000,
    "lastLogin": 1710600000000,
    "lastLogout": 1710590000000,
    "online": true,
    "totalExp": 84250000,
    "bedwars": {
      "level": 245,
      "prestige": "Stone",
      "coins": 850000,
      "overall": { "wins": 1200, "losses": 800, "winRate": 60.0, "wlr": 1.5, "kills": 5000, "deaths": 3000, "kdr": 1.67, "finalKills": 2500, "finalDeaths": 1000, "fkdr": 2.5, "bedsBroken": 1800, "bedsLost": 900, "bblr": 2.0, "winstreak": 5, "gamesPlayed": 2000 },
      "modes": { "solo": { ... }, "doubles": { ... }, "threes": { ... }, "fours": { ... } }
    },
    "skywars": {
      "level": 18,
      "prestige": "Iron",
      "coins": 250000,
      "souls": 450,
      "overall": { "wins": 800, "losses": 600, "winRate": 57.14, "wlr": 1.33, "kills": 3000, "deaths": 2000, "assists": 500, "kdr": 1.5, "gamesPlayed": 1400 },
      "modes": { "solo_normal": { ... }, "solo_insane": { ... }, "team_normal": { ... }, "team_insane": { ... } }
    }
  },
  "meta": { "cached": false, "api_version": "v1" }
}

The /stats endpoint makes a single Hypixel API call — the same as any individual player endpoint. Use it when you need multiple stat categories to avoid redundant requests.

Errors (all player endpoints)

Code	HTTP Status	When
`BAD_REQUEST`	400	Invalid username format (must be 1-16 chars, `[a-zA-Z0-9_]`)
`NOT_FOUND`	404	Player not found on Mojang/Hypixel
`UPSTREAM_ERROR`	502	Hypixel or Mojang API returned an error
`TIMEOUT`	503	Upstream timed out and no cached data available

Getting started

Guides

GET /v1/player/:username

Path parameters

Examples

Response

GET /v1/player/:username/bedwars

Path parameters

Example

Response

GET /v1/player/:username/skywars

Path parameters

Example

Response

GET /v1/player/:username/stats

Path parameters

Example

Response

Errors (all player endpoints)