Answers to the questions we get most often.
Because the official API has no name search. It can look up an exact tag and nothing else — there is no endpoint that takes a name and returns players.
So name search runs against a local index instead. Every profile opened here is stored, and the name is stored with it, which is what makes the player findable later. On the first start with a live token the index is also seeded by walking the official trophy leaderboards for global and dozens of countries, so a fresh install is not completely empty.
Search by tag once and the player joins the index permanently. Previous names are kept too, so a rename does not lose them — that is what the include previous names option on the search page reads.
The refresh loop asks the API about every indexed tag on a schedule. When the API answers 404 — the account was deleted, or the tag never existed — the row is dropped along with its name and club history. Keeping it would mean spending requests on a tag that can only ever fail, and leaving a ghost in the search results.
Every fetch returns the payload plus where it came from. api means the profile was pulled from Supercell during this page render. cache means the stored copy was still inside its freshness window — three minutes for players, ten for clubs — or that the live call failed and the last good copy was served instead of an error page. demo means no API token is configured and the page is showing the deterministic generator.
This instance is currently running against the live API.
That is the whole battle log the API offers: the most recent 25 battles, with no paging and no date range. Anything longer has to be accumulated.
So every time a profile is opened, whatever is new in those 25 battles is copied into a local archive, keyed so the same battle is never stored twice. A player who is viewed regularly — or bookmarked, which puts them in the fast refresh band — builds up a much longer history than 25 matches over time. The per-battle archive is pruned after 90 days.
The breakdowns on the battles tab are computed from the current 25-match window, which is why they can swing sharply after a single session.
From the archived battles, aggregated per day, mode, map and bracket. A tier list reads the last seven days for the selected filter and ignores any brawler with fewer than 200 picks in that window.
The score is not raw win rate. Each brawler’s wins are first blended with the pool average by adding roughly 1,500 pseudo-battles at the global win rate — an empirical-Bayes shrink. A brawler with 210 games and a hot streak is pulled back toward the mean; one with 40,000 games barely moves. A log-scaled popularity term is then added with a small weight, so a brawler nobody plays does not top the list on the strength of a niche win rate.
Letters are standard-deviation bands around the mean score of that pool, not fixed win-rate thresholds. S sits roughly 1.25 standard deviations above the mean, and anything more than about one below lands in D, the lowest band. That means tiers are always relative to the map you are looking at.
A map-specific tier list needs a real sample before it means anything. If fewer than 5,000 battles have been archived for that mode, map and bracket, the page falls back to a deterministic generator and says so at the top rather than quietly showing a tier list built from 80 games. Popular ranked maps fill up first; obscure event maps may stay on the fallback for a long time.
A derived number, and it is labelled that way everywhere it appears. The API exposes no play-time counter at all — only victory counts.
It works backwards from those: 3v3 victories imply roughly twice as many games at a typical win rate, Showdown firsts imply far more, each game is multiplied by an average match length for its mode, and account level covers everything that is not a counted victory. Expect it to be within about 15% for a normal account, and further off for anyone who plays mostly friendlies or event modes.
Yes, if it is in the top half. The API gives a rank rather than a result for Showdown, so finishing in the top 5 of a 10-player solo match, or the top 3 of a 5-team duo match, is counted as a win everywhere win rates appear — the cut is the top half rounded up, which is why an odd number of duo teams gives the middle place to the winning side. Draws are tracked separately and excluded from the win-rate denominator.
There is no ladder-population endpoint. Nobody outside Supercell can count how many players sit in each rank. The distribution page shows a modelled shape with an estimated total, and the live counts it can show are only over the profiles this instance has indexed — a sample, not the ladder. Treat the shape as informative and the absolute numbers as an estimate.
The API returns a brawler’s id, name, gadgets, star powers, gears and hypercharges — but not its rarity or class. Those come from a bundled table matched by name. A brawler released after that table was last updated has no entry, so it is marked unknown, drawn in neutral grey, and left out of rarity totals instead of being assigned a plausible-looking guess. The bundled roster was last synced on 2026-09-15, and the calculator tables follow the in-game values as of 2026-09-16.
Two mechanisms overlap. Opening a page fetches the profile directly if the stored copy is older than its window — three minutes for a player, ten for a club.
In the background, a poller wakes every 30 seconds and spends a budget of about 100 requests per cycle on whatever is most overdue, rate-limited so the whole process stays inside the token’s limits. Priority decides what gets that budget: anyone bookmarked or viewed in the last hour is refreshed every couple of minutes, anyone viewed in the last day every quarter of an hour, and everything else once every six hours. That profile pass only pulls a battle log alongside the profile for the first two bands.
Battle logs themselves are not limited to those bands. A separate harvest pass — normally about half of each cycle’s budget — walks the whole index by how long it has been since each account’s log was last collected, cold accounts included, fetching a log for any player not harvested in the last half hour. An account nobody has viewed still plays matches, and those matches are what build the tier-list sample.
On a serverless host there is no long-lived process to hold that interval, so the poller is switched off and an external scheduler calls the cron endpoint instead.
Supercell API keys are pinned to fixed IP addresses. If the server’s public IP changes — a new host, a dynamic residential address, a different egress node — every request starts failing with a 403 that specifically means “wrong IP”.
When that happens the refresh cycle stops early instead of burning its whole budget on requests that cannot succeed, records the error and a hint about the cause, and pages fall back to the last cached copy — so the site keeps working, just frozen. The fix is to create a new key for the current public IP at developer.brawlstars.com, put it in the environment and restart.
A username, a salted scrypt hash of the password, a preferred language, two timestamps, and a verified email address: registration sends a 6-digit code to it and the account is only created once you enter that code. The address is used to verify itself and to send account-security notices, and here is everything this site can send to it — generated from the code that sends them, not written out by hand:
No newsletter, and it is never shared with anyone. It is also the only way back in: “Forgot your password?” on the sign-in page sends a reset code, and only ever to an account's VERIFIED address. An account with no address, or with one that was never verified, cannot recover a forgotten password at all — so add and verify one in your account settings while you still can.
On top of that: up to 25 bookmarks and the last 25 profiles you viewed, both tied to the account so they follow you between devices, and a session cookie that lasts 90 days. That is what registration itself creates, not a complete inventory: an avatar, a bound player tag, uploaded images, chat and direct messages, board posts and friends are all kept against the account as you add them — and section 2 of the privacy policy renders the complete list straight from the database schema. Deleting the account removes the address, the bookmarks, the history and the sessions with it. An address you type on a bug report is a separate thing that belongs to that report, not to the account.
It needs Node 22 or newer, because persistence uses Node’s built-in SQLite — there is no native module to compile and no database server to install. Install dependencies, then start the dev server on port 3000.
It runs without an API token: everything falls back to a deterministic generator, and a demo directory is seeded so name search has something to return. Add a token to the local environment file and restart, and the synthetic rows are purged on the first live boot so they can never leak into search results or leaderboards.
The bundled game data (brawlers, gadgets, star powers, hypercharges) is refreshed by the sync script rather than being fetched at runtime.
No. It is unofficial fan content, built on the public Brawl Stars API and not endorsed by Supercell — the same notice sits in the footer of every page, next to the link to Supercell’s Fan Content Policy.
Anything not covered here is probably in Technology or Search Specification.
