# Chess.com API

> Chess.com returns player stats, recent games, and top player rankings as a workflow and API.

Chess.com (Chesscom) returns public player profiles, ratings, records, best puzzle ratings, and Puzzle Rush scores from a username or profile link. List recent games returns completed public games for a username and selected month, with optional game speed and result limit. List top players returns ranked players for a selected time control, with ratings, records, and profile links.

- Page: https://fous.com/workflows/chess-com
- Handle: `@chess-com`
- Category: [Entertainment](https://fous.com/workflows/category/entertainment)
- Source website: https://chess.com
- Last verified: Sep 29, 2026
- Fous is not affiliated with Chess.com.

## Methods

### Get player stats

Operation `get_player_stats`, version 1. 1 credit per call.

Get a Chess.com player’s public profile, ratings, game records, best puzzle rating and Puzzle Rush best score from a username or profile link. Unplayed time controls and unpublished values are null.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `username` | string | yes | `"https://www.chess.com/member/MagnusCarlsen"` | Player’s Chess.com username or profile link, for example Hikaru or https://www.chess.com/member/Hikaru. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "username"
  ],
  "properties": {
    "username": {
      "type": "string",
      "description": "Player’s Chess.com username or profile link, for example Hikaru or https://www.chess.com/member/Hikaru.",
      "examples": [
        "https://www.chess.com/member/MagnusCarlsen",
        "Hikaru",
        "ericrosen"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "username": "https://www.chess.com/member/MagnusCarlsen"
    },
    {
      "username": "Hikaru"
    },
    {
      "username": "ericrosen"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `blitz` | object or null |  | Null when this time control has never been played. |
| `blitz.wins` | integer or null | `4942` |  |
| `blitz.draws` | integer or null | `838` |  |
| `blitz.losses` | integer or null | `1104` |  |
| `blitz.best_rating` | integer or null | `3410` | Highest published rating. |
| `blitz.current_rating` | integer or null | `3402` | Most recently published rating. |
| `blitz.best_rating_date` | string or null | `"2026-06-24"` | Date of highest published rating. |
| `daily` | object or null |  | Null when this time control has never been played. |
| `daily.wins` | integer or null | `73` |  |
| `daily.draws` | integer or null | `4` |  |
| `daily.losses` | integer or null | `11` |  |
| `daily.best_rating` | integer or null | `2464` | Highest published rating. |
| `daily.current_rating` | integer or null | `2239` | Most recently published rating. |
| `daily.best_rating_date` | string or null | `"2014-04-10"` | Date of highest published rating. |
| `rapid` | object or null |  | Null when this time control has never been played. |
| `rapid.wins` | integer or null | `135` |  |
| `rapid.draws` | integer or null | `110` |  |
| `rapid.losses` | integer or null | `32` |  |
| `rapid.best_rating` | integer or null | `2977` | Highest published rating. |
| `rapid.current_rating` | integer or null | `2941` | Most recently published rating. |
| `rapid.best_rating_date` | string or null | `"2023-02-06"` | Date of highest published rating. |
| `title` | string or null | `"GM"` |  |
| `bullet` | object or null |  | Null when this time control has never been played. |
| `bullet.wins` | integer or null | `1519` |  |
| `bullet.draws` | integer or null | `222` |  |
| `bullet.losses` | integer or null | `494` |  |
| `bullet.best_rating` | integer or null | `3390` | Highest published rating. |
| `bullet.current_rating` | integer or null | `3270` | Most recently published rating. |
| `bullet.best_rating_date` | string or null | `"2023-03-27"` | Date of highest published rating. |
| `country` | string or null | `"Norway"` | Country name. |
| `username` | string | `"magnuscarlsen"` |  |
| `followers` | integer or null | `318642` |  |
| `is_streamer` | boolean or null | `false` |  |
| `joined_date` | string or null | `"2010-08-26"` |  |
| `display_name` | string or null | `"Magnus Carlsen"` |  |
| `profile_link` | string | `"https://www.chess.com/member/MagnusCarlsen"` |  |
| `last_online_date` | string or null | `"2026-09-28"` |  |
| `avatar_image_link` | string or null | `"https://images.chesscomfiles.com/uploads/v1/user/3889224.121e2094.200x200o.361c2f8a59c2.jpg"` |  |
| `best_puzzle_rating` | integer or null | `400` |  |
| `puzzle_rush_best_score` | integer or null | `123` |  |

**Example input**

```json
{
  "username": "https://www.chess.com/member/MagnusCarlsen"
}
```

**Example output**

```json
{
  "blitz": {
    "wins": 4942,
    "draws": 838,
    "losses": 1104,
    "best_rating": 3410,
    "current_rating": 3402,
    "best_rating_date": "2026-06-24"
  },
  "daily": null,
  "rapid": {
    "wins": 135,
    "draws": 110,
    "losses": 32,
    "best_rating": 2977,
    "current_rating": 2941,
    "best_rating_date": "2023-02-06"
  },
  "title": "GM",
  "bullet": {
    "wins": 1519,
    "draws": 222,
    "losses": 494,
    "best_rating": 3390,
    "current_rating": 3270,
    "best_rating_date": "2023-03-27"
  },
  "country": "Norway",
  "username": "magnuscarlsen",
  "followers": 318642,
  "is_streamer": false,
  "joined_date": "2010-08-26",
  "display_name": "Magnus Carlsen",
  "profile_link": "https://www.chess.com/member/MagnusCarlsen",
  "last_online_date": "2026-09-28",
  "avatar_image_link": "https://images.chesscomfiles.com/uploads/v1/user/3889224.121e2094.200x200o.361c2f8a59c2.jpg",
  "best_puzzle_rating": 400,
  "puzzle_rush_best_score": null
}
```

### List recent games

Operation `list_recent_games`, version 1. 1 credit per call.

List a player’s games for a month, newest first, with results, ratings, opening and game links. Defaults to the current UTC month; only completed public games in the selected month are included.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `month` | string | no | `"2026-09"` | Month of games in YYYY-MM, for example 2026-09. Defaults to the current UTC month. |
| `username` | string | yes | `"erik"` | Chess.com username, for example MagnusCarlsen. |
| `max_results` | integer | no | `2` | Maximum number of games, for example 50. Defaults to 50. |
| `time_control` | string | no | `"daily"` | Game speed, for example blitz. Defaults to all. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "username"
  ],
  "properties": {
    "month": {
      "type": "string",
      "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$",
      "description": "Month of games in YYYY-MM, for example 2026-09. Defaults to the current UTC month.",
      "examples": [
        "2026-09",
        "2026-10"
      ]
    },
    "username": {
      "type": "string",
      "minLength": 1,
      "description": "Chess.com username, for example MagnusCarlsen.",
      "examples": [
        "erik",
        "MagnusCarlsen"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 50,
      "maximum": 500,
      "minimum": 1,
      "description": "Maximum number of games, for example 50. Defaults to 50.",
      "x-fous-developer": true,
      "examples": [
        2,
        3
      ]
    },
    "time_control": {
      "enum": [
        "all",
        "rapid",
        "blitz",
        "bullet",
        "daily"
      ],
      "type": "string",
      "default": "all",
      "description": "Game speed, for example blitz. Defaults to all.",
      "examples": [
        "daily",
        "blitz",
        "all"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "month": "2026-09",
      "username": "erik",
      "max_results": 2,
      "time_control": "daily"
    },
    {
      "month": "2026-09",
      "username": "MagnusCarlsen",
      "max_results": 3,
      "time_control": "blitz"
    },
    {
      "month": "2026-10",
      "username": "MagnusCarlsen",
      "max_results": 3,
      "time_control": "all"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `games` | array |  |  |
| `games[].pgn` | string or null |  |  |
| `games[].color` | string | `"black"` |  |
| `games[].rated` | string | `"yes"` |  |
| `games[].result` | string | `"loss"` |  |
| `games[].end_time` | string | `"2026-09-28T23:06:15+00:00"` | Date and time the game ended in UTC. |
| `games[].game_link` | string | `"https://www.chess.com/game/daily/1035606720"` |  |
| `games[].how_it_ended` | string or null | `"resignation"` |  |
| `games[].opening_name` | string or null | `"Modern Defense with 1 d4"` |  |
| `games[].time_control` | string | `"1 day per move"` |  |
| `games[].player_rating` | integer or null | `1402` |  |
| `games[].opponent_rating` | integer or null | `1289` |  |
| `games[].opponent_username` | string | `"NorwegianViking82"` |  |
| `games[].final_position_fen` | string or null | `"r1b1rnqb/pppk3p/6p1/4npB1/8/2N2BP1/PPP1P2P/2KRRNQ1 b - - 3 9"` |  |

**Example input**

```json
{
  "month": "2026-09",
  "username": "erik",
  "max_results": 2,
  "time_control": "daily"
}
```

**Example output**

```json
{
  "games": [
    {
      "pgn": "[Event \"Let's Play! - Chess960\"]\n[Site \"Chess.com\"]\n[Date \"2026.09.27\"]\n[Round \"-\"]\n[White \"NorwegianViking82\"]\n[Black \"erik\"]\n[Result \"1-0\"]\n[Variant \"Chess960\"]\n[SetUp \"1\"]\n[FEN \"rnbkrnqb/pppppppp/8…",
      "color": "black",
      "rated": "yes",
      "result": "loss",
      "end_time": "2026-09-28T23:06:15+00:00",
      "game_link": "https://www.chess.com/game/daily/1035606720",
      "how_it_ended": "resignation",
      "opening_name": "Modern Defense with 1 d4",
      "time_control": "1 day per move",
      "player_rating": 1402,
      "opponent_rating": 1289,
      "opponent_username": "NorwegianViking82",
      "final_position_fen": "r1b1rnqb/pppk3p/6p1/4npB1/8/2N2BP1/PPP1P2P/2KRRNQ1 b - - 3 9"
    },
    {
      "pgn": "[Event \"Let's Play! - Chess960\"]\n[Site \"Chess.com\"]\n[Date \"2026.09.19\"]\n[Round \"-\"]\n[White \"erik\"]\n[Black \"NorwegianViking82\"]\n[Result \"1-0\"]\n[Variant \"Chess960\"]\n[SetUp \"1\"]\n[FEN \"rqbknrnb/pppppppp/8…",
      "color": "white",
      "rated": "yes",
      "result": "win",
      "end_time": "2026-09-27T12:28:43+00:00",
      "game_link": "https://www.chess.com/game/daily/1031528548",
      "how_it_ended": "resignation",
      "opening_name": "Kings Fianchetto Opening",
      "time_control": "1 day per move",
      "player_rating": 1429,
      "opponent_rating": 1311,
      "opponent_username": "NorwegianViking82",
      "final_position_fen": "6r1/pp3r2/2p4P/3pBkP1/3P4/1P6/P2KP3/6R1 w - - 0 32"
    }
  ]
}
```

### List top players

Operation `list_top_players`, version 1. 1 credit per call.

List up to 50 top Chess.com players by time control, in rank order, with ratings, game records and profile links. Puzzles rankings use puzzle scores; records are shown where published.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `max_results` | integer | no | `10` | Maximum number of ranked players, for example 10. |
| `time_control` | string | no | `"blitz"` | Leaderboard category, for example blitz. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "max_results": {
      "type": "integer",
      "default": 50,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum number of ranked players, for example 10.",
      "x-fous-developer": true,
      "examples": [
        10,
        5,
        3
      ]
    },
    "time_control": {
      "enum": [
        "rapid",
        "blitz",
        "bullet",
        "daily",
        "puzzles"
      ],
      "type": "string",
      "default": "blitz",
      "description": "Leaderboard category, for example blitz.",
      "examples": [
        "blitz",
        "rapid",
        "puzzles"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "max_results": 10,
      "time_control": "blitz"
    },
    {
      "max_results": 5,
      "time_control": "rapid"
    },
    {
      "max_results": 3,
      "time_control": "puzzles"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `players` | array |  |  |
| `players[].name` | string or null | `"Hikaru Nakamura"` | Displayed full name, when available. |
| `players[].rank` | integer or null | `1` | Leaderboard position. |
| `players[].wins` | integer or null | `37427` | Published win count, when available. |
| `players[].draws` | integer or null | `4412` | Published draw count, when available. |
| `players[].title` | string or null | `"GM"` | Chess title, when available. |
| `players[].losses` | integer or null | `5648` | Published loss count, when available. |
| `players[].rating` | integer or null | `3469` | Leaderboard rating or puzzle score. |
| `players[].country` | string or null | `"United States"` | Displayed country name, when available. |
| `players[].username` | string | `"Hikaru"` | Chess.com username. |
| `players[].profile_link` | string | `"https://www.chess.com/member/Hikaru"` | Player profile page. |

**Example input**

```json
{
  "max_results": 10,
  "time_control": "blitz"
}
```

**Example output**

```json
{
  "players": [
    {
      "name": "Hikaru Nakamura",
      "rank": 1,
      "wins": 37427,
      "draws": 4412,
      "title": "GM",
      "losses": 5648,
      "rating": 3469,
      "country": "United States",
      "username": "Hikaru",
      "profile_link": "https://www.chess.com/member/Hikaru"
    },
    {
      "name": "Magnus Carlsen",
      "rank": 2,
      "wins": 5126,
      "draws": 850,
      "title": "GM",
      "losses": 1133,
      "rating": 3402,
      "country": "Norway",
      "username": "MagnusCarlsen",
      "profile_link": "https://www.chess.com/member/MagnusCarlsen"
    },
    {
      "name": "Ediz Gürel",
      "rank": 3,
      "wins": 3244,
      "draws": 644,
      "title": "GM",
      "losses": 2450,
      "rating": 3339,
      "country": "Turkey",
      "username": "gurelediz",
      "profile_link": "https://www.chess.com/member/gurelediz"
    }
  ]
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@chess-com",
  "visibility": "public",
  "operation": "get_player_stats",
  "version": 1,
  "input": {
    "username": "https://www.chess.com/member/MagnusCarlsen"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@chess-com\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_player_stats\",\n  \"version\": 1,\n  \"input\": {\n    \"username\": \"https://www.chess.com/member/MagnusCarlsen\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@chess-com",
  "visibility": "public",
  "operation": "get_player_stats",
  "version": 1,
  "input": {
    "username": "https://www.chess.com/member/MagnusCarlsen"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@chess-com","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Compare player ratings and records across time controls
- Review a player's recent games and openings
- Filter recent games by month or game speed
- Track top players by time control
- Find ranked players' profile links and countries

## FAQ

### Is Fous affiliated with Chess.com?

No. Fous is not affiliated with Chess.com. This workflow reads the public chess.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a Chess.com account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from chess.com when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 29, 2026.

### What are a player's current and best ratings?

Get player stats returns published current and best ratings by time control for a username or profile link.

### What games did a player recently finish?

List recent games returns completed public games for a username and month, newest first.

### Who are the top players by time control?

List top players returns ranked players for a selected time control.

## Related

- [MLB API](https://fous.com/workflows/mlb.md): MLB provides scores, schedules and game details for one date or up to seven days, regular-season division standings defaulting to the current year, and player profiles with regular-season stats for a selected season and career.
- [NHL API](https://fous.com/workflows/nhl.md): NHL provides games, schedules, and scores when published, standings by date, and player profiles with regular-season stats; dates outside a season have no teams, and unavailable stats are null.
- [Twitch API](https://fous.com/workflows/twitch.md): Twitch returns channel profiles, live status, up to 10 broadcasts, top streams, viewer-ranked categories, up to 100 public videos/clips, and 1–30-day schedules; counts change.
- [Yahoo Sports API](https://fous.com/workflows/yahoo-sports.md): Yahoo Sports returns date-based scores and schedules, seasonal standings, and player regular-season and career stats when Yahoo provides them; unavailable data may be missing.
- [ESPN API](https://fous.com/workflows/espn.md): ESPN provides daily scores and schedules, team results, player statistics, matchup summaries, and latest topic-specific headlines; coverage and published details vary, especially for college and soccer.
- [Roblox API](https://fous.com/workflows/roblox.md): Explore and play community-created Roblox experiences, find experiences by name or link, and browse current Charts rankings with player counts and other details.
- [Steam API](https://fous.com/workflows/steam.md): Steam returns game details, country-specific prices, reviews, and current and historical player counts, plus player rankings and sales lists; some details or prices may be unavailable, and review totals span languages and verdicts.
- [ATP Tour API](https://fous.com/workflows/atp-tour.md): ATP Tour provides official men's tennis rankings as of their latest publication and tournament results, including champions, for a specified year or most recent listed edition.
- [All Entertainment workflows](https://fous.com/workflows/category/entertainment)