Brawlhalla APIbrawlhalla.com ↗
Query Brawlhalla ranked leaderboards by region, game mode, and player name. Returns Elo ratings, tier labels, rank positions, and team data.
What is the Brawlhalla API?
The Brawlhalla Rankings API exposes the ranked leaderboard data from brawlhalla.com through a single search_rankings endpoint returning up to 14 response fields per entry. Each result includes a player's rank, Elo rating, and tier label across four game modes — 1v1, 2v2, solo_2v2, and 3v3 — with support for region filtering, paginated traversal, and fuzzy name search.
curl -X GET 'https://api.parse.bot/scraper/bcc90fc6-37a1-4d21-b7d1-d1035cd59238/search_rankings?region=ALL&search=Lopes&game_mode=1v1' \ -H 'X-API-Key: $PARSE_API_KEY'
Returns one page of the Brawlhalla ranked leaderboard for a region and game mode, ordered by rank. Each row is one leaderboard entry: a single player in 1v1, solo_2v2 and 3v3, or a two-player team in 2v2 (the players array carries every member with its numeric player_id and current username). Rows carry the current season Elo rating, the peak rating for the season, wins, losses, tier and home region. An optional search term filters entries whose username resembles the term (the site's matching is fuzzy, so loosely related names may also appear); when a search is supplied, rows come from across the whole leaderboard and ranks are not contiguous. Pagination is caller-controlled through page (1-based, default 1) and max_results (rows per page, default 25, clamped to 50); total_pages and has_more describe the remaining pages for the same filters, and a page beyond total_pages returns an empty rankings array. One upstream request per call. Unknown region or game_mode values are rejected before any request.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based page number within the result set for the given filters. |
| region | string | Leaderboard region to query. ALL spans every region. |
| search | string | Username to search for (case-insensitive, fuzzy). Omitted = the full leaderboard in rank order. |
| game_mode | string | Ranked queue whose leaderboard is returned. 2v2 rows are two-player teams; the other modes are single players. |
| max_results | integer | Rows per page; values above 50 are clamped to 50. |
{
"type": "object",
"fields": {
"page": "page number returned",
"region": "region code the results were queried with",
"search": "search term applied, or null when none",
"has_more": "boolean, true when page < total_pages",
"rankings": "array of leaderboard entries in rank order",
"game_mode": "game mode the results were queried with",
"max_results": "effective rows-per-page after clamping",
"total_pages": "total number of pages available for these filters (from the site)",
"rankings[].rank": "integer leaderboard position within the queried region/mode",
"rankings[].tier": "ranked tier label such as Diamond, Platinum 2, Gold 1",
"rankings[].wins": "integer ranked wins this season",
"rankings[].losses": "integer ranked losses this season",
"rankings[].rating": "current season Elo rating (integer)",
"rankings[].region": "home region code of the entry",
"rankings[].players": "array of {player_id (integer), username} — one member for solo modes, two for 2v2 teams",
"rankings[].peak_rating": "highest Elo rating reached this season (integer)"
},
"sample": {
"data": {
"page": 1,
"region": "EU",
"search": null,
"has_more": true,
"rankings": [
{
"rank": 1,
"tier": "Diamond",
"wins": 105,
"losses": 45,
"rating": 2465,
"region": "EU",
"players": [
{
"username": "Blaze",
"player_id": 1766641
},
{
"username": "acno?",
"player_id": 2768493
}
],
"peak_rating": 2472
},
{
"rank": 2,
"tier": "Diamond",
"wins": 85,
"losses": 26,
"rating": 2427,
"region": "EU",
"players": [
{
"username": "Blew",
"player_id": 919693
},
{
"username": "Kresuu",
"player_id": 2926802
}
],
"peak_rating": 2429
}
],
"game_mode": "2v2",
"max_results": 10,
"total_pages": 2422
},
"status": "success"
}
}About the Brawlhalla API
What the API Returns
The search_rankings endpoint returns one page of the Brawlhalla ranked leaderboard for a given region and game mode. Each entry in the rankings array includes rank (integer leaderboard position), tier (a string label such as "Diamond" or "Platinum 2"), and a players array containing each participant's numeric player_id. In 2v2 mode the players array carries two members; in 1v1, solo_2v2, and 3v3 modes each entry represents a single player.
Filtering and Pagination
The region parameter accepts a region code or ALL to span every region. The game_mode parameter selects which ranked queue to query. Setting search performs a case-insensitive, fuzzy match against usernames, returning matching entries rather than the full leaderboard in rank order. Pages are 1-based and controlled by the page parameter; the max_results parameter sets rows per page with a hard ceiling of 50. The response always includes total_pages and has_more so callers can paginate programmatically without guessing.
Response Shape
Top-level response fields include page, region, game_mode, search (null when no search term was supplied), max_results (the effective value after clamping), total_pages, and has_more. The rankings array is ordered by rank within the queried region and mode, making it straightforward to build leaderboard views, monitor rank movement over time, or resolve a username to its current Elo and tier.
The Brawlhalla API is a managed, monitored endpoint for brawlhalla.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when brawlhalla.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official brawlhalla.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display a regional 1v1 leaderboard sorted by rank with tier badges drawn from the
tierfield - Look up a specific player's current rank and Elo by passing their username to the
searchparameter - Track rank changes over time by polling
search_rankingsfor a known player_id and loggingranksnapshots - Build a 2v2 team lookup tool that resolves both
player_idvalues from a single leaderboard entry - Compare rank distributions across regions by iterating the
regionparameter and aggregatingtiercounts - Paginate through an entire game mode's leaderboard using
total_pagesandhas_morefor data export
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Brawlhalla have an official developer API?+
What does the `search` parameter actually match against?+
search is omitted, the endpoint returns the full leaderboard in ascending rank order for the given region and game_mode.Are individual player stats like win/loss record or legend-specific Elo returned?+
Is there a limit on how many results can be returned per request?+
max_results parameter controls rows per page, but values above 50 are clamped to 50. To retrieve more entries, increment the page parameter and continue until has_more returns false or page equals total_pages.