Brawlhalla APIbrawlhalla.com ↗
Access Brawlhalla ranked leaderboards by region and game mode, the full legend roster with bios, crossover characters, and news articles via a single API.
What is the Brawlhalla API?
This API covers 6 endpoints for Brawlhalla data: ranked leaderboard pages filterable by region and game mode via search_rankings, the complete legend roster and per-legend detail pages, every crossover character with source franchise info, and a paginated news archive with full article bodies. Each leaderboard entry exposes rank, tier, player IDs, and team composition; each legend record includes weapons, lore biography in both HTML and plain text, and splash art URLs.
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'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace brawlhalla-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Brawlhalla SDK — legends, news, rankings, and crossovers."""
from parse_apis.brawlhalla_com_api import Brawlhalla, Region, GameMode, InputNotFound
client = Brawlhalla()
# Browse the legend roster and drill into one legend's full bio
legend_summary = client.legend_summaries.list(limit=1).first()
if legend_summary is not None:
print(legend_summary.name, "-", legend_summary.subtitle)
legend = legend_summary.details()
print(legend.bio_text[:120])
print("Weapons:", ", ".join(w.name for w in legend.weapons))
# Point-lookup a legend by slug (derived from a summary above)
if legend_summary is not None:
detail = client.legends.get(slug=legend_summary.slug)
print(detail.name, detail.url)
# Latest news — list summaries then fetch the full article
article_summary = client.article_summaries.list(per_page=5, limit=1).first()
if article_summary is not None:
print(article_summary.title, article_summary.date_gmt)
article = article_summary.details()
print(article.content_text[:200])
# Crossovers — each links back to its base legend
for xover in client.crossovers.list(limit=3):
base = xover.legend.name if xover.legend else "unknown"
print(f"{xover.name} (base legend: {base})")
# Top-ranked 1v1 players in Europe
for entry in client.rankings.list(region=Region.EU, game_mode=GameMode.MODE_1V1, limit=5):
names = ", ".join(p.username for p in entry.players)
print(f"#{entry.rank} {names} — {entry.rating} Elo ({entry.tier})")
# Search for a player by name across all regions
hit = client.rankings.list(search="Lopes", limit=1).first()
if hit is not None:
player = hit.players[0]
print(f"Found {player.username} (id {player.player_id}) at rank {hit.rank}")
# Graceful handling of a missing legend
try:
client.legends.get(slug="no-such-legend")
except InputNotFound:
print("Unknown legend slug handled gracefully")
print("exercised: legend_summaries.list / legends.get / article_summaries.list"
" / ArticleSummary.details / crossovers.list / rankings.list / InputNotFound")
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
Ranked Leaderboards
The search_rankings endpoint returns one page of the Brawlhalla ranked leaderboard. Filter by region (use ALL to span every region), game_mode (1v1, 2v2, solo_2v2, 3v3), and page. Each entry in the rankings array includes the player's rank, tier label (e.g. Diamond, Platinum 2), and a players array carrying each member's numeric player_id. In 2v2 mode the players array contains two members; all other modes carry one. Pass a search string for fuzzy, case-insensitive username lookup. Results cap at 50 rows per page (max_results); the has_more and total_pages fields tell you whether additional pages exist.
Legend Roster and Detail
list_legends returns the full roster in site display order — no pagination required. Each entry includes the legend's name, slug, subtitle, icon URL, and a weapons array of {name, slug} pairs. Pass any slug to get_legend for the full detail record: bio_html and bio_text (lore biography in both rendered HTML and plain text), splash art URL (may be null), the opaque site id, and the same weapons and subtitle fields. list_crossovers covers every crossover character in a single request, each row linking back to its base legend via a {name, slug} object and listing sources franchises plus a video_url (YouTube trailer or null).
News Archive
list_news paginates the news archive newest-first. Each article summary includes id, slug, title, excerpt, date_gmt, author, categories, and tags. Pass a slug to get_news_article to retrieve the complete article: content_html (rendered HTML body) plus all the same summary fields. The per_page parameter accepts up to 100 articles per request and the total field reflects the full count of published articles.
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?+
- Track a player's ranked tier and leaderboard position across regions using search_rankings with a username search
- Build a legend picker tool displaying each character's weapons and lore using list_legends and get_legend
- Populate a crossover character browser showing source franchises and trailer links from list_crossovers
- Aggregate Brawlhalla patch notes and news into a Discord bot using list_news and get_news_article
- Monitor top-100 Diamond rankings per game mode for meta analysis using search_rankings with max_results and page
- Generate a static legend wiki with biography text and splash art from get_legend bio_text and splash fields
- Surface new crossover announcements by polling list_news and filtering by categories or tags
| 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.