Player Profiles

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.

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

GET /v1/profile/:username

Returns all SkyBlock profiles for a Minecraft player. Cache: 15 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/profile/Refraction"

const response = await fetch("https://api.skytools.app/v1/profile/Refraction", {
  headers: { "X-API-Key": "sk_your_key_here" },
});
const { data } = await response.json();
console.log(`UUID: ${data.uuid}`);
console.log(`Profiles: ${data.profiles.length}`);

import requests

response = requests.get(
    "https://api.skytools.app/v1/profile/Refraction",
    headers={"X-API-Key": "sk_your_key_here"},
)
data = response.json()["data"]
print(f"UUID: {data['uuid']}, Profiles: {len(data['profiles'])}")

Response

{
  "success": true,
  "data": {
    "uuid": "b876ec32e396476ba1158438d83c67d4",
    "username": "Refraction",
    "profiles": [
      {
        "profile_id": "a1b2c3d4e5f6",
        "cute_name": "Strawberry",
        "selected": true,
        "skyblockLevel": 312,
        "members": { ... }
      }
    ]
  },
  "meta": { "cached": false, "api_version": "v1" }
}

Field	Type	Description
`uuid`	string	Player’s Minecraft UUID
`username`	string	Player’s current username
`profiles`	array	All SkyBlock profiles
`profiles[].profile_id`	string	Unique profile ID
`profiles[].cute_name`	string	Profile fruit name (e.g. “Strawberry”)
`profiles[].selected`	boolean	`true` if this is the player’s active profile
`profiles[].skyblockLevel`	integer	SkyBlock level for this profile (derived from `leveling.experience / 100`)
`profiles[].members`	object	Profile member data (keyed by UUID)

GET /v1/profile/:username/networth

Returns a full net worth breakdown for a player’s SkyBlock profile. Cache: 5 minutes

Path parameters

Parameter	Type	Description
`username`	string	Minecraft username

Query parameters

Parameter	Type	Default	Description
`profile_id`	string	—	Specific profile ID. If omitted, uses the selected profile.

Example

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

Response

{
  "success": true,
  "data": {
    "uuid": "b876ec32e396476ba1158438d83c67d4",
    "username": "Refraction",
    "networth": { ... }
  },
  "meta": { "cached": false, "api_version": "v1" }
}

Net worth is computed server-side using current bazaar/auction prices. The breakdown includes categories like armor, inventory, pets, accessories, storage, etc.

GET /v1/profile/:username/items

Returns parsed inventory items for a player’s SkyBlock profile. Cache: 5 minutes

Path parameters

Parameter	Type	Description
`username`	string	Minecraft username

Query parameters

Parameter	Type	Default	Description
`profile_id`	string	—	Specific profile ID. If omitted, uses the selected profile.

Example

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

Response

{
  "success": true,
  "data": {
    "uuid": "b876ec32e396476ba1158438d83c67d4",
    "username": "Refraction",
    "items": { ... }
  },
  "meta": { "cached": false, "api_version": "v1" }
}

GET /v1/profile/:username/museum

Returns museum data for a player’s SkyBlock profile. Cache: 15 minutes

Path parameters

Parameter	Type	Description
`username`	string	Minecraft username

Query parameters

Parameter	Type	Default	Description
`profile_id`	string	—	Specific profile ID. If omitted, uses the selected profile.

Example

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

Response

{
  "success": true,
  "data": {
    "uuid": "b876ec32e396476ba1158438d83c67d4",
    "username": "Refraction",
    "museum": { ... }
  },
  "meta": { "cached": false, "api_version": "v1" }
}

GET /v1/profile/:username/garden

Returns the garden for a player’s SkyBlock profile — crop milestones, unlocked plots, composter state and visitor data (raw Hypixel garden payload). Cache: 10 minutes

Query parameters

Parameter	Type	Default	Description
`profile_id`	string	—	Specific profile ID. If omitted, uses the selected profile.

Example

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

Response

{
  "success": true,
  "data": {
    "profileId": "a1b2c3d4e5f6",
    "garden": { "garden_experience": 12345678, "unlocked_plots_ids": ["beginner_1"], "resources_collected": { ... } }
  },
  "meta": { "cached": false, "api_version": "v1" }
}

If the profile has no garden created, garden is null (the request still succeeds with a 200).

GET /v1/profile/:username/auctions

Returns the player’s own active auctions on a SkyBlock profile (their listings, not the global auction house). Cache: 60 seconds

Query parameters

Parameter	Type	Default	Description
`profile_id`	string	—	Specific profile ID. If omitted, uses the selected profile.

Example

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

Response

{
  "success": true,
  "data": {
    "profileId": "a1b2c3d4e5f6",
    "auctions": [
      {
        "uuid": "abc123def456",
        "item_name": "Hyperion",
        "starting_bid": 900000000,
        "highest_bid_amount": 0,
        "bin": true,
        "end": 1706100000000
      }
    ]
  },
  "meta": { "cached": false, "api_version": "v1" }
}

Returns an empty auctions array when the player has no active listings on the profile.

GET /v1/profile/resolve-usernames

Batch reverse lookup: resolve up to 24 player UUIDs to their current usernames in one request. Useful for hydrating leaderboard rows, auction sellers, or guild members. Cache: 24 hours

Query parameters

Parameter	Type	Default	Description
`uuids`	string	—	Comma-separated list of UUIDs (with or without dashes), max 24. Invalid entries are dropped; duplicates are deduplicated.

Example

curl -H "X-API-Key: sk_your_key_here" \
  "https://api.skytools.app/v1/profile/resolve-usernames?uuids=b876ec32e396476ba1158438d83c67d4,5f4f4a1d..."

Response

{
  "success": true,
  "data": {
    "names": {
      "b876ec32e396476ba1158438d83c67d4": "Refraction",
      "5f4f4a1d...": null
    }
  },
  "meta": { "cached": false, "api_version": "v1" }
}

Field	Type	Description
`names`	object	Map of dashless UUID → username, or `null` if the UUID could not be resolved

An empty or all-invalid uuids list returns { "names": {} }. Passing more than 24 UUIDs returns a 400 BAD_REQUEST.

Per-player bingo progress lives at GET /v1/profile/:username/bingo. See the Bingo page.

Errors (all profile 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/profile/:username

Path parameters

Examples

Response

GET /v1/profile/:username/networth

Path parameters

Query parameters

Example

Response

GET /v1/profile/:username/items

Path parameters

Query parameters

Example

Response

GET /v1/profile/:username/museum

Path parameters

Query parameters

Example

Response

GET /v1/profile/:username/garden

Query parameters

Example

Response

GET /v1/profile/:username/auctions

Query parameters

Example

Response

GET /v1/profile/resolve-usernames

Query parameters

Example

Response

Errors (all profile endpoints)