For developers

GuildLB API

Read-only access to the guild and player leaderboard data behind GuildLB, plus shared blacklists for alliance guilds.

Responses are JSON and come from GuildLB's cache, so they are fast but can be up to a few days old. Nothing here calls Hypixel on your behalf.

Base URL
https://guildlb.com

Authentication

Every endpoint needs an API key. Send it in the x-api-key header, or as Authorization: Bearer YOUR_API_KEY. Keep it on your server; never ship it in a browser app or a public repository.

Website key
Guild, player and networth lookups. Issued by hand: request one below.
Guild key
The alliance blacklist and scammer endpoints, acting as one guild. The guild master of an alliance guild creates it under Settings, API key on the guild page. It stops working within about 10 minutes of a guild master change, and at once if the guild leaves the alliance.
Your first request
curl "https://guildlb.com/api/player/ExamplePlayer" \
  -H "x-api-key: YOUR_API_KEY"

API terms

Using a GuildLB API key means you agree to these terms.

Not a Hypixel API proxy
GuildLB serves its own cached leaderboard data. If you need raw Hypixel data, use the Hypixel API with your own key.
Free for your users
Do not put anything built on this API behind a paywall or use it for commercial purposes.
Credit GuildLB
Show a visible link to guildlb.com wherever the data appears.
Follow the rules you already agreed to
Use the API within Hypixel's developer policies and our Terms of Service.
Keys can be revoked
We can revoke any key at any time, for example for breaking these terms or putting too much load on the API.

Rate limits

Each key gets 120 requests per minute unless we agreed a different limit. Every response reports the window in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Over the limit you get 429 RATE_LIMITED; wait for the Retry-After seconds before trying again. Cache what you fetch instead of polling: most of it changes over hours or days.

Headers
HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1792370645

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Responses and errors

Every response has the same envelope: success, then data on success or error with a code and message on failure. Any endpoint can return:

401UNAUTHORIZED
The key is missing, invalid, revoked, or the wrong type for this endpoint.
429RATE_LIMITED
Too many requests. Honor Retry-After.
503AUTH_UNAVAILABLE
Key checks are briefly unavailable. Retry after a few seconds.
Envelope
{
  "success": true,
  "data": {
    "name": "ExamplePlayer"
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
Website key

Guilds

Guild lookups.

GET/api/guild/{name}

Get a guild by name

Cached guild data, up to a few days old.

Needs a website key

Parameters

namerequiredpath · string
Guild name.

Responses

200
The guild, its metrics and members. Abridged.
404
No matching resource.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/guild/Example%20Guild" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "id": "0123456789abcdef0123456789abcdef",
    "name": "Example Guild",
    "level": 120,
    "skillavg": 52.4,
    "slayers": 1850000,
    "catacombs": 48.3,
    "networth": 41200000000,
    "networth_formatted": "41.20B",
    "slayers_formatted": "1.85M",
    "placement": 12,
    "is_alliance": false,
    "top_skill": null,
    "top_rank": null,
    "discord_link": "https://discord.gg/example",
    "discordUrl": "https://discord.gg/example",
    "iconUrl": "https://guildlb.com/api/guild/Example%20Guild/icon",
    "bannerUrl": null,
    "bannerPos": null,
    "bio": "An example guild.",
    "preferred_games": [],
    "memberCount": 2,
    "members": [
      {
        "uuid": "01234567-89ab-cdef-0123-456789abcdef",
        "name": "ExamplePlayer",
        "guild_id": "0123456789abcdef0123456789abcdef",
        "guild_name": "Example Guild",
        "guild_rank": "Guild Master",
        "skyblock_level": 312,
        "skills": 54.1,
        "slayers": 950000,
        "catacombs": 51.2,
        "networth": 2300000000
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 900
  }
}
GET/api/guild/{name}/activity

Get recent guild joins and leaves

Cached join and leave events from the last 90 days, newest first. Events are detected when the guild is refreshed, so a leave is timed to the refresh that noticed it.

Needs a website key

Parameters

namerequiredpath · string
Guild name.
limitquery · integer · default 100 · max 500
Maximum events to return.

Responses

200
Join and leave events. Empty when none are recorded.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/guild/Example%20Guild/activity" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "events": [
      {
        "uuid": "01234567-89ab-cdef-0123-456789abcdef",
        "username": "ExamplePlayer",
        "type": "join",
        "occurred_at": "2026-10-17T18:04:00.000Z"
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 900
  }
}
Website key

Players

Player lookups.

GET/api/player/{name}

Get a player by name

Cached player totals, up to a few days old. Untracked players return 404.

Needs a website key

Parameters

namerequiredpath · string
Minecraft username (1-16 letters, digits or underscores) or UUID.

Responses

200
Level, skills, slayers, catacombs, networth, weights and guild. Abridged.
400
VALIDATION_ERROR: the name is not a valid Minecraft username or UUID.
404
PLAYER_NOT_TRACKED. Not queued.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/player/ExamplePlayer" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "ExamplePlayer",
    "guild_id": "0123456789abcdef0123456789abcdef",
    "guild_name": "Example Guild",
    "guild_rank": "Guild Master",
    "skyblock_level": 312,
    "skills": 54.1,
    "slayers": 950000,
    "catacombs": 51.2,
    "networth": 2300000000,
    "non_cosmetic_networth": 2100000000,
    "networth_formatted": "2.30B",
    "slayers_formatted": "950.00K",
    "updated_at": "2026-10-05T11:30:00Z"
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 900
  }
}
Website key

Events

Guild event standings.

GET/api/events

List a guild's events

Events the named guild takes part in. Guild names match case-insensitively. Cached for a minute. Website keys need the events scope. Alliance guild keys are also accepted and only see their own guild.

Needs a website key

Parameters

guildrequiredquery · string
Guild name.

Responses

200
Events for the guild. Empty when none. guildB is null for a solo event.
400
VALIDATION_ERROR: the guild query parameter is missing.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/events" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "data": [
    {
      "id": "evt_123",
      "name": "Example Showdown",
      "mode": "networth",
      "status": "active",
      "startAt": "2026-10-01T00:00:00Z",
      "endAt": "2026-11-01T00:00:00Z",
      "guildA": {
        "id": "0123456789abcdef0123456789abcdef",
        "name": "Example Guild"
      },
      "guildB": {
        "id": "fedcba9876543210fedcba9876543210",
        "name": "Other Guild"
      }
    }
  ],
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 60
  }
}
GET/api/events/{id}

Get an event standing

Live standings for one event: guild points and per-member points. Cached for a minute. Website keys need the events scope. Alliance guild keys are also accepted and only see their own guild.

Needs a website key

Parameters

idrequiredpath · string
Event id.

Responses

200
The event, guild totals and member points. Abridged.
404
EVENT_NOT_FOUND: no event has this id.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/events/example" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "event": {
      "id": "evt_123",
      "name": "Example Showdown",
      "guildA": "0123456789abcdef0123456789abcdef",
      "guildB": "fedcba9876543210fedcba9876543210",
      "startAt": "2026-10-01T00:00:00Z",
      "endAt": "2026-11-01T00:00:00Z",
      "mode": "networth",
      "status": "active"
    },
    "guilds": [
      {
        "id": "0123456789abcdef0123456789abcdef",
        "name": "Example Guild",
        "points": 1200,
        "updatedAt": "2026-10-30T00:00:00Z"
      }
    ],
    "members": [],
    "asOf": "2026-10-30T00:00:00Z"
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 60
  }
}
Website key

Player assets

Player networth.

GET/api/player/{name}/networth

Get a player's networth

Cached total and non-cosmetic networth, up to a few days old. Untracked players return 404.

Needs a website key

Parameters

namerequiredpath · string
Minecraft username (1-16 letters, digits or underscores) or UUID.

Responses

200
total, nonCosmetic and updatedAt. breakdown is always null.
400
VALIDATION_ERROR: the name is not a valid Minecraft username or UUID.
404
PLAYER_NOT_TRACKED. Not queued.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/player/ExamplePlayer/networth" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "total": 2300000000,
    "nonCosmetic": 2100000000,
    "updatedAt": "2026-10-05T11:30:00Z",
    "breakdown": null
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 900
  }
}
Website key

Market

Cached SkyBlock item prices.

GET/api/prices

Get cached item prices

Batch prices from GuildLB's cached bazaar and auction data, up to 100 ids per request. Bazaar items return buy and sell; auction items return the lowest BIN and a recent median. Ids without data return source null and a reason.

Needs a website key

Parameters

idsrequiredquery · string
Comma-separated uppercase SkyBlock item ids, 1 to 100. Duplicates are ignored.

Responses

200
prices keyed by item id.
400
VALIDATION_ERROR: ids is missing, has more than 100 entries, or contains an invalid id.
503
PRICES_UNAVAILABLE: the cached market data could not be read.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/prices" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "prices": {
      "ENCHANTED_DIAMOND": {
        "source": "bazaar",
        "buy": 1620.4,
        "sell": 1498.2,
        "updatedAt": "2026-10-05T11:59:00Z"
      },
      "HYPERION": {
        "source": "auction",
        "lowestBin": 905000000,
        "median": 931000000,
        "updatedAt": "2026-10-05T11:58:00Z"
      },
      "NOT_AN_ITEM": {
        "source": null,
        "reason": "no_price_data"
      }
    }
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z",
    "ttl": 60
  }
}
Website key

API key

Details about the key you call with.

GET/api/key

Get your API key details

Name, type, rate limit and request counts for the key on this request. Never describes any other key. Counts as a normal request.

Needs a website key

Responses

200
rateLimit and usage are null when that data is unavailable.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/key" \
  -H "x-api-key: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "type": "website",
    "name": "My bot",
    "createdAt": "2026-09-01T10:00:00.000Z",
    "expiresAt": null,
    "rateLimit": {
      "max": 120,
      "windowSeconds": 60,
      "used": 3,
      "remaining": 117,
      "resetsAt": "2026-10-05T12:01:00.000Z"
    },
    "usage": {
      "today": 42,
      "last7Days": 310,
      "rateLimitedLast7Days": 0
    }
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
Guild key

Guild blacklist

Shared blacklists for alliance guilds.

GET/api/alliance/blacklist/check/{player}

Check a player against the alliance blacklist

Shared alliance entries plus your guild's private ones. Accepts a username or UUID.

Needs a guild key

Parameters

playerrequiredpath · string
Player UUID or username.

Responses

200
Whether the player is blacklisted, and the matching entries.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/alliance/blacklist/check/ExamplePlayer" \
  -H "x-api-key: YOUR_GUILD_KEY"
Response
{
  "success": true,
  "data": {
    "blacklisted": true,
    "entries": [
      {
        "guildId": "0123456789abcdef0123456789abcdef",
        "guildName": "Example Guild",
        "category": "SCAMMING",
        "reason": "Chargeback scam",
        "addedBy": "123456789012345678",
        "public": true,
        "createdAt": "2026-08-08T12:00:00Z"
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
GET/api/alliance/scammer/{player}

Check if a player is a known scammer

SkyBlockZ plus shared alliance scamming entries. Accepts a username or UUID. Can take a few seconds.

Needs a guild key

Parameters

playerrequiredpath · string
Player UUID or username.

Responses

200
scammer is true if any source flags the player. skyblockz_status: flagged, clear or unknown.
400
A required field was missing or malformed.
404
No Minecraft account has that username or UUID.
502
The lookup failed upstream. Retry later.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/alliance/scammer/ExamplePlayer" \
  -H "x-api-key: YOUR_GUILD_KEY"
Response
{
  "success": true,
  "data": {
    "uuid": "0123456789abcdef0123456789abcdef",
    "name": "ExamplePlayer",
    "scammer": true,
    "skyblockz_status": "flagged",
    "flags": [
      {
        "source": "SkyBlockZ",
        "reason": "Coop scam"
      },
      {
        "source": "Guild Alliance",
        "reason": "Chargeback scam"
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
GET/api/guild/blacklist

Get your guild's blacklist

Your guild's own blacklist.

Needs a guild key

Responses

200
The calling guild's blacklist entries.

Plus the common errors (401, 429).

Request
curl "https://guildlb.com/api/guild/blacklist" \
  -H "x-api-key: YOUR_GUILD_KEY"
Response
{
  "success": true,
  "data": [
    {
      "playerUuid": "0123456789abcdef0123456789abcdef",
      "category": "SCAMMING",
      "reason": "Chargeback scam",
      "addedBy": "123456789012345678",
      "public": true,
      "createdAt": "2026-08-08T12:00:00Z"
    }
  ],
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
POST/api/guild/blacklist

Add a player to your guild blacklist

Adds a player by UUID. Returns 409 if they are already listed; remove them first to change the entry.

Needs a guild key

Request body

playerUuidrequiredstring
The player UUID to blacklist.
categorySCAMMING | CHEATING | TOXICITY | ALT_ABUSE | OTHER
Defaults to OTHER.
reasonstring
Optional free-text detail.
addedByrequiredstring
Discord user ID of the staff member adding it.
publicboolean
Share with the alliance. Defaults to true; false keeps it on your list only.

Responses

200
The saved entry: id, playerUuid, category and public.
400
A required field was missing or malformed.
403
The calling guild is not an alliance guild.
409
The player is already on this guild's blacklist; the message includes the existing reason.

Plus the common errors (401, 429).

Request
curl -X POST "https://guildlb.com/api/guild/blacklist" \
  -H "x-api-key: YOUR_GUILD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerUuid":"0123456789abcdef0123456789abcdef","category":"SCAMMING","reason":"Chargeback scam","addedBy":"123456789012345678","public":true}'
Response
{
  "success": true,
  "data": {
    "id": 42,
    "playerUuid": "0123456789abcdef0123456789abcdef",
    "category": "SCAMMING",
    "public": true
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}
DELETE/api/guild/blacklist/{player}

Remove a player from your guild blacklist

Removes a player by UUID.

Needs a guild key

Parameters

playerrequiredpath · string
Player UUID to remove.

Responses

200
The player was removed.
404
No matching resource.

Plus the common errors (401, 429).

Request
curl -X DELETE "https://guildlb.com/api/guild/blacklist/0123456789abcdef0123456789abcdef" \
  -H "x-api-key: YOUR_GUILD_KEY"
Response
{
  "success": true,
  "data": {
    "removed": true
  },
  "meta": {
    "generatedAt": "2026-10-05T12:00:00.000Z"
  }
}

Request a key

Website keys are issued by hand. Tell us what you are building and we will reach out.