A player's games, newest first: players and ratings, result and termination, time control and class, rated, opening and ECO, accuracies (chess.com), rating change (lichess), final position and full PGN. chess.com: one month at a time (default the latest; months lists every month with games). lichess: the latest games; pass next_until back as until for older ones. Filters: time_class, color, result, opponent and rated work on both sites (chess.com: within the month fetched); since and analysed on lichess. When a filter is given the answer also has applied_filters.
Every response includes credits_used: the credits this call cost.
Parameters
name
type
description
usernamerequired
string
Username. Example: hikaru
site
chesscom | lichess
chesscom or lichess. Default: chesscom
month
string
YYYY-MM: games of that month. Example: 2024-01
limit
integer
Games to return (chess.com 1-500, lichess 1-100; default 50).
lichess only: true rated games only, false casual only.
until
string
lichess only: next_until from the previous page.
time_class
bullet | blitz | rapid | daily | classical
Only games of this time class: bullet, blitz, rapid, daily (lichess: correspondence) or classical (lichess). On lichess it stands in for perf when perf is not given.
color
white | black
Only games the player had this colour in.
result
win | loss | draw
Only games the player won, lost or drew. On lichess it is applied to the page of games fetched, so a page can hold fewer than limit games; keep paging with next_until.
opponent
string
Only games against this username.
since
string
lichess only: games played from this date (YYYY-MM-DD or epoch milliseconds).
analysed
true | false
lichess only: true for games with computer analysis, false for games without.
import os, requests
res = requests.get(
"https://api.api.sh/chess/v1/games",
params={"username": "hikaru"},
headers={"x-api-key": os.environ["APISH_KEY"]},
timeout=120,
)
res.raise_for_status()
data = res.json()
const url = new URL("https://api.api.sh/chess/v1/games");
url.searchParams.set("username", "hikaru");
const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
Response
A JSON object with the fields described above, plus raw (the source's own data), cached, fetched_at and credits_used. Errors return {"success": false, "error": "…"} with the HTTP status (see errors). A lookup that ran but found nothing (404) costs the price above; refused calls and errors on our side are free (what's charged).
The fastest way to see the full response is the playground: it runs this endpoint with your account and shows the exact JSON.