Pokémon Showdown Users, Ladder & News API Reference

The Pokémon Showdown Users & Ladder API exposes player profiles, per-format ladder standings, and site news as straightforward JSON resources. All endpoints are served with Access-Control-Allow-Origin: *, meaning you can call them directly from client-side JavaScript with no server-side proxy. The general pattern throughout the PS website is that appending .json to any URL returns a machine-readable version of the same page — the endpoints documented here follow that convention.

Ladder rankings use three rating systems simultaneously: Elo (displayed rating), GXE (Glicko X-Act Estimate — percentage chance of winning a random rated battle), and Glicko-1 (the underlying statistical model stored as r ± rd with a decay factor). The rpr/rprd pair shown in the UI are the Glicko-1 values after recent-play adjustment.

User Info (with Ladder Data)

GET https://pokemonshowdown.com/users/{username}.json Returns the public profile of a registered user, including their ladder standings across every format they have played. This is the same data shown on a user’s profile page.

curl https://pokemonshowdown.com/users/zarel.json

Path parameters

username

string

required

The player’s Pokémon Showdown username. The server normalises it to a lowercase ID internally, so capitalisation is ignored.

Response

The response includes basic profile metadata alongside an array of ladder entries (one per format the user has played rated games in).

userid

string

The canonical lowercase user ID (e.g. "zarel").

username

string

Display name with original capitalisation (e.g. "Zarel").

ratings

object

An object keyed by format ID, where each value is a ladder entry for that format. See the LadderEntry fields section below for the shape of each entry.

Ladder

GET https://pokemonshowdown.com/ladder/{format}.json Returns the top-500 leaderboard for a specific battle format. The response shape is defined by the LadderData type used inside the client’s panel-ladder.tsx panel.

curl https://pokemonshowdown.com/ladder/gen8ou.json

Path parameters

format

string

required

The format ID to retrieve standings for (e.g. gen8ou, gen9randombattle, gen7ubers). Must be an exact, canonical format ID.

Optional query parameter

prefix

string

Filter the leaderboard to usernames beginning with this prefix (lowercased to a user ID). Used by the in-client ladder search feature. When omitted, the full top-500 list is returned.

Response

formatid

string

The canonical format ID (e.g. "gen8ou"). Matches the path parameter.

format

string

Human-readable format name (e.g. "[Gen 8] OU").

toplist

LadderEntry[]

Ordered array of ranked players, highest Elo first. Up to 500 entries.

Show LadderEntry fields

userid

string

Lowercase user ID (e.g. "zarel").

username

string

Display name with capitalisation preserved.

number

Total wins in this format (all-time, not just the rating period).

number

Total losses in this format.

number

Total ties in this format.

gxe

number

Glicko X-Act Estimate. The player’s estimated probability (as a percentage, 0–100) of winning a randomly selected rated game in this format. Displayed as e.g. "83.4%" in the client.

number

Raw Glicko-1 rating value (before recent-play adjustment).

number

Raw Glicko-1 rating deviation (before recent-play adjustment). Values above 100 indicate a provisional rating.

sigma

number

Glicko-1 volatility parameter (σ).

rptime

number

Unix timestamp of the last rating period calculation affecting this entry.

rpr

number

Recent-play adjusted Glicko-1 rating. This is displayed in the ladder table as the primary Glicko-1 value (e.g. "1850 ± 42").

rprd

number

Recent-play adjusted rating deviation. Shown alongside rpr as the ± figure. A deviation above 100 marks the rating as provisional.

rpsigma

number

Recent-play adjusted volatility parameter.

elo

number

Current Elo rating. This is the primary displayed ranking value. Rounded to a whole number for display (e.g. 1823).

first_played

number | null

Unix timestamp of the user’s first rated game in this format, or null if unavailable.

last_played

number | null

Unix timestamp of the user’s most recent rated game in this format, or null if unavailable.

coil

number

COIL score (optional). Only present for formats that use the COIL ranking system. When at least one entry in toplist has coil, the client renders a COIL column in the ladder table.

Example JSON response (abbreviated)

{
  "formatid": "gen8ou",
  "format": "[Gen 8] OU",
  "toplist": [
    {
      "userid": "exampleplayer",
      "username": "ExamplePlayer",
      "w": 312,
      "l": 87,
      "t": 2,
      "gxe": 88.3,
      "r": 1901.4,
      "rd": 28.6,
      "sigma": 0.06,
      "rptime": 1711584000,
      "rpr": 1895.1,
      "rprd": 34.2,
      "rpsigma": 0.06,
      "elo": 1957,
      "first_played": 1609459200,
      "last_played": 1711497600
    }
  ]
}

The ladder table in the Pokémon Showdown client displays Elo, GXE, and Glicko-1 (rpr ± rprd) as its three rating columns. When building your own leaderboard UI, these three fields are the most meaningful to surface.

News

List all news articles

GET https://pokemonshowdown.com/news.json Returns an array of news article summaries in reverse-chronological order.

curl

curl https://pokemonshowdown.com/news.json

fetch

const articles = await fetch("https://pokemonshowdown.com/news.json").then(
  (r) => r.json()
);
for (const article of articles) {
  console.log(article.id, article.title);
}

Response

[].id

number

Numeric article identifier. Use this to fetch the full article body.

[].title

string

Article headline.

Get a single news article

GET https://pokemonshowdown.com/news/{id}.json Returns the full content of a single news article by ID.

curl https://pokemonshowdown.com/news/270.json

number

required

The numeric news article ID (e.g. 270). Obtain valid IDs from the list endpoint above.

Response

number

The article’s numeric ID.

title

string

Article headline.

content

string

Full article body, typically HTML-formatted.

Quick-Reference

User Profile

GET /users/{username}.json — profile and all-format ladder stats for a player

Format Ladder

GET /ladder/{format}.json — top-500 leaderboard with Elo, GXE, and Glicko-1

News List

GET /news.json — reverse-chronological index of all news articles

Single Article

GET /news/{id}.json — full content of one news article by ID

Core

Battle

Web API

Pokémon Showdown Users, Ladder & News API Reference

User Info (with Ladder Data)

Path parameters

Response

Ladder

Path parameters

Optional query parameter

Response

Example JSON response (abbreviated)

News

List all news articles

Response

Get a single news article

Response

Quick-Reference

User Profile

Format Ladder

News List

Single Article

Build docs developers (and LLMs) love

Core

Battle

Web API

Documentation Index

​User Info (with Ladder Data)

​Path parameters

​Response

​Ladder

​Path parameters

​Optional query parameter

​Response

​Example JSON response (abbreviated)

​News

​List all news articles

​Response

​Get a single news article

​Response

​Quick-Reference

User Profile

Format Ladder

News List

Single Article

Build docs developers (and LLMs) love

User Info (with Ladder Data)

Path parameters

Response

Ladder

Path parameters

Optional query parameter

Response

Example JSON response (abbreviated)

News

List all news articles

Response

Get a single news article

Response

Quick-Reference