# Chess.com API: List recent games

> Lists a Chess.com player's completed public games for a month, newest first, with results, ratings, opening and game links.

Unofficial. Not affiliated with or endorsed by Chess.com.

- Page: https://fous.com/methods/chess.com/list-recent-games
- Method: `chess.com/list_recent_games`, version 1
- Website: chess.com
- Returns: games with end time, color, ratings, opponent, result, how it ended, time control, opening, game link, PGN and final position
- Effect: read (it gets data and changes nothing)
- Sign-in: none needed
- Cost: 1 credit per completed run (1¢ with pay as you go); failed runs are free
- Verified: Nov 2, 2026

## Inputs

| Field | Type | Required | In the run below | 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 | `"MagnusCarlsen"` | Chess.com username, for example MagnusCarlsen. |
| `max_results` | integer | no | `3` | Maximum number of games, for example 50. Defaults to 50. Default 50. |
| `time_control` | string | no | `"blitz"` | Game speed, for example blitz. Defaults to all. One of "all", "rapid", "blitz", "bullet", "daily". Default "all". |

## Output

From a run on Oct 23, 2026, shortened. Its input:

```json
{
  "month": "2026-09",
  "username": "MagnusCarlsen",
  "max_results": 3,
  "time_control": "blitz"
}
```

Its output:

```json
{
  "games": [
    {
      "pgn": "[Event \"Live Chess\"]\n[Site \"Chess.com\"]\n[Date \"2026.09.30\"]\n[Round \"-\"]\n[White \"MagnusCarlsen\"]\n[Black \"jcibarra\"]\n[Result \"1-0\"]\n[CurrentPosition \"8/5pk1/p3p1N1/5q2/5r2/6Q1/P4RPK/4R3 b - - 2 39\"]\n[Timezone \"UTC\"]\n[ECO \"B40\"]\n[ECOUrl \"https://www.chess.com/openings/Sicilian-Defense-French-Variation\"…",
      "color": "white",
      "rated": "yes",
      "result": "win",
      "end_time": "2026-09-30T17:32:17+00:00",
      "game_link": "https://www.chess.com/game/live/185102910785",
      "how_it_ended": "resignation",
      "opening_name": "Sicilian Defense French Variation",
      "time_control": "5 min",
      "player_rating": 3379,
      "opponent_rating": 3124,
      "opponent_username": "jcibarra",
      "final_position_fen": "8/5pk1/p3p1N1/5q2/5r2/6Q1/P4RPK/4R3 b - - 2 39"
    },
    {
      "pgn": "[Event \"Live Chess\"]\n[Site \"Chess.com\"]\n[Date \"2026.09.30\"]\n[Round \"-\"]\n[White \"jcibarra\"]\n[Black \"MagnusCarlsen\"]\n[Result \"0-1\"]\n[CurrentPosition \"4r3/3Rb3/p4k2/1p5p/1P2K3/r7/P3R3/8 w - - 0 43\"]\n[Timezone \"UTC\"]\n[ECO \"B33\"]\n[ECOUrl \"https://www.chess.com/openings/Sicilian-Defense-Open-Pelikan-and-S…",
      "color": "black",
      "rated": "yes",
      "result": "win",
      "end_time": "2026-09-30T17:23:58+00:00",
      "game_link": "https://www.chess.com/game/live/185102311045",
      "how_it_ended": "resignation",
      "opening_name": "Sicilian Defense Open Pelikan and Sveshnikov Variations",
      "time_control": "5 min",
      "player_rating": 3376,
      "opponent_rating": 3127,
      "opponent_username": "jcibarra",
      "final_position_fen": "4r3/3Rb3/p4k2/1p5p/1P2K3/r7/P3R3/8 w - - 0 43"
    },
    {
      "pgn": "[Event \"Live Chess\"]\n[Site \"Chess.com\"]\n[Date \"2026.09.30\"]\n[Round \"-\"]\n[White \"MagnusCarlsen\"]\n[Black \"MentalistMate\"]\n[Result \"1-0\"]\n[Tournament \"https://www.chess.com/tournament/live/chess-club-showdown-31104532\"]\n[CurrentPosition \"8/8/2Q5/pPk2p2/P1p5/2P2NP1/4rPK1/3q4 b - - 6 55\"]\n[Timezone \"UTC\"…",
      "color": "white",
      "rated": "yes",
      "result": "win",
      "end_time": "2026-09-30T16:55:41+00:00",
      "game_link": "https://www.chess.com/game/live/184613271140",
      "how_it_ended": "checkmate",
      "opening_name": "Caro Kann Defense Exchange Rubinstein Variation",
      "time_control": "5 min",
      "player_rating": 3373,
      "opponent_rating": 2578,
      "opponent_username": "MentalistMate",
      "final_position_fen": "8/8/2Q5/pPk2p2/P1p5/2P2NP1/4rPK1/3q4 b - - 6 55"
    }
  ]
}
```

## Run it

From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output:

```bash
curl https://api.fous.com/v1/runs \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"chess.com/list_recent_games","input":{"month":"2026-09","username":"MagnusCarlsen","max_results":3,"time_control":"blitz"}}'
```

From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`.

## Ask your agent

- Show me the completed public games for the player hikaru in March 2026, newest first, with results and opening names.
- I want a list of blitz games played by MagnusCarlsen last month, including ratings and game links.
- Pull up to 20 rapid games from user nakamura_fan for 2025-11 with the opponent names and how each game ended.
- Can you get the bullet games for the username chessqueen42 in 2026-01, along with the PGN for each one?
- List my daily correspondence games for September 2026 on chess.com under the account kasparov_jr, sorted newest first.

## Input schema

```json
{
  "type": "object",
  "required": [
    "username"
  ],
  "properties": {
    "month": {
      "type": "string",
      "description": "Month of games in YYYY-MM, for example 2026-09. Defaults to the current UTC month."
    },
    "username": {
      "type": "string",
      "minLength": 1,
      "description": "Chess.com username, for example MagnusCarlsen."
    },
    "max_results": {
      "type": "integer",
      "default": 50,
      "maximum": 500,
      "minimum": 1,
      "description": "Maximum number of games, for example 50. Defaults to 50."
    },
    "time_control": {
      "enum": [
        "all",
        "rapid",
        "blitz",
        "bullet",
        "daily"
      ],
      "type": "string",
      "default": "all",
      "description": "Game speed, for example blitz. Defaults to all."
    }
  },
  "additionalProperties": false
}
```

## Output schema

```json
{
  "type": "object",
  "required": [
    "games"
  ],
  "properties": {
    "games": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "end_time",
          "color",
          "player_rating",
          "opponent_username",
          "opponent_rating",
          "result",
          "how_it_ended",
          "time_control",
          "rated",
          "opening_name",
          "game_link",
          "pgn",
          "final_position_fen"
        ],
        "properties": {
          "pgn": {
            "type": [
              "string",
              "null"
            ]
          },
          "color": {
            "enum": [
              "white",
              "black"
            ],
            "type": "string"
          },
          "rated": {
            "enum": [
              "yes",
              "no"
            ],
            "type": "string"
          },
          "result": {
            "enum": [
              "win",
              "loss",
              "draw"
            ],
            "type": "string"
          },
          "end_time": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time the game ended in UTC."
          },
          "game_link": {
            "type": "string"
          },
          "how_it_ended": {
            "type": [
              "string",
              "null"
            ]
          },
          "opening_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "time_control": {
            "type": "string"
          },
          "player_rating": {
            "type": [
              "integer",
              "null"
            ]
          },
          "opponent_rating": {
            "type": [
              "integer",
              "null"
            ]
          },
          "opponent_username": {
            "type": "string"
          },
          "final_position_fen": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}
```

## See more

- [Chess.com API: List top players](https://fous.com/methods/chess.com/list-top-players.md): Lists up to 50 top Chess.com players for a time control, in rank order, with ratings, game records and profile links. Puzzles rankings use puzzle scores.
- [Chess.com API: Get player stats](https://fous.com/methods/chess.com/get-player-stats.md): Gets a Chess.com player's public profile, ratings and game records, best puzzle rating and Puzzle Rush best score from a username or member profile link.
- [Roblox API: List top games](https://fous.com/methods/roblox.com/list-top-games.md): Lists ranked Roblox experiences from a current Charts list. Each game includes players online, approval percentage, creator, icon and game link.
- [Bluesky API: List recent posts](https://fous.com/methods/bsky.app/list-recent-posts.md): Lists an account's latest public Bluesky posts, newest first. Replies and reposts are left out unless requested; a repost's time is when the account reposted it.
- [UEFA API: Get competition matches](https://fous.com/methods/uefa.com/get-competition-matches.md): Gets UEFA club competition matches in a date range, with kick-off times in a chosen time zone, scores, stages and venues. You can limit the list to one club.
- [MLB API: Get scores and schedule](https://fous.com/methods/mlb.com/get-scores.md): Lists MLB games and scores for a date or up to seven days, optionally for one team. Start times are shown in the requested time zone.
- [Medium API: List a writer's or publication's latest articles](https://fous.com/methods/medium.com/list-author-articles.md): Lists the latest public articles by a Medium writer or publication (by username, publication name or Medium link), with dates, reading times, claps, member-only labels and tags.
- [Kick API: List live streams](https://fous.com/methods/kick.com/list-live-streams.md): Lists the most-watched live Kick streams right now, optionally in one category and language, sorted by current viewers.
- [All Chess.com methods](https://fous.com/methods/chess.com.md)