# Lichess Scraper · Players, Games, Ratings & Tournaments (`reapx/lichess-scraper`) Actor Scrape Lichess player profiles, 13 game variant rating leaderboards (bullet, blitz, rapid, classical, chess960, ultraBullet, etc.), FIDE titles, total games, play time, and profile metadata. Fast HTTP API scraper charging per returned record with tiered pricing. - **URL**: https://apify.com/reapx/lichess-scraper.md - **Developed by:** [Tarek Etman](https://apify.com/reapx) (community) - **Categories:** Games, Sports - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.30 / 1,000 record returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ![reapX — public sources in, addressable records out](https://reapx.dev/reapx.gif) ## Lichess Scraper · Players, Games, Ratings & Tournaments Scrape Lichess player profiles, rating leaderboards across 13 game variants (Bullet, Blitz, Rapid, Classical, UltraBullet, Chess960, Crazyhouse, Antichess, Atomic, Horde, King of the Hill, Racing Kings, Three-Check), FIDE titles (GM, WGM, IM, WIM, FM, WFM, CM, WCM), country rankings, total games, play time, and profile metadata. Extracts structured data directly from the official public Lichess API over plain HTTP with no login or API key required. > Maintained by **reapX**. Every row cites the Apify run that produced it — nothing is inferred, modelled or filled in, and a field absent from the source is absent from the row. The extracted archive for this source is browsable at [reapx.dev/data/lichess-scraper/](https://reapx.dev/data/lichess-scraper/) and mirrored as an open dataset on [Hugging Face](https://huggingface.co/datasets/reapxdev/lichess-scraper) and [Kaggle](https://www.kaggle.com/datasets/reapxdev/lichess-scraper). Questions: reapxdev@proton.me *** ### Overview & Key Features **Lichess Scraper** is a production-ready, high-speed scraper designed to extract comprehensive chess player statistics, ratings, and profile metadata from [Lichess.org](https://lichess.org). Built specifically for data scientists, chess researchers, tournament organizers, and gaming analysts, this actor collects clean, addressable player records without relying on browser automation or headful scraping. #### Feature Highlights - **13 Game Variants Supported**: Scrape top players across standard time controls (Bullet, Blitz, Rapid, Classical) and specialized chess variants (UltraBullet, Chess960 / Fischer Random, Crazyhouse, Antichess, Atomic, Horde, King of the Hill, Racing Kings, Three-Check). - **Official Title Filtering**: Filter by FIDE and Lichess titles including Grandmaster (GM), Woman Grandmaster (WGM), International Master (IM), Woman International Master (WIM), FIDE Master (FM), Woman FIDE Master (WFM), Candidate Master (CM), Woman Candidate Master (WCM), and official BOT accounts. - **Geographic & Rating Search**: Search and filter players by ISO 2-letter country code (US, NO, IN, FR, DE, ES, RU, CN, etc.) and custom minimum/maximum rating thresholds. - **Team Scrape Support**: Extract profiles for members of official or custom Lichess teams (e.g., `titled-players`, `all-grandmasters`). - **Direct Handle Scrapes**: Target specific Lichess usernames directly to fetch full multi-variant rating matrices and play history. - **Pay-Per-Event Billing**: Pay only for complete player records returned. Empty results or rate-limited errors incur zero charge. *** ### ⬇️ Input The actor accepts structured JSON input specifying game variant filters, title filters, country codes, rating limits, specific player handles, or team memberships. | Parameter | Type | Required | Default | Description | | :--- | :--- | :--- | :--- | :--- | | `perfType` | String | No | `"bullet"` | **Game variant filter.** Leaderboard mode: `bullet`, `blitz`, `rapid`, `classical`, `ultraBullet`, `crazyhouse`, `chess960`, `kingOfTheHill`, `threeCheck`, `antichess`, `atomic`, `horde`, `racingKings`, or `all`. | | `titleFilter` | String | No | `"all"` | **Title filter.** Filter players by title: `all`, `GM`, `WGM`, `IM`, `WIM`, `FM`, `WFM`, `CM`, `WCM`, or `BOT`. | | `countryFilter` | String | No | `""` | **Country filter.** Filter by ISO 2-letter country code (e.g. `US`, `NO`, `IN`, `FR`, `DE`, `ES`, `RU`, `CN`). | | `minRating` | Integer | No | `0` | **Minimum rating limit.** Lower threshold for player ratings across active variants. | | `maxRating` | Integer | No | `4000` | **Maximum rating limit.** Upper rating ceiling for player records. | | `usernames` | Array | No | `[]` | **Target Lichess usernames.** Array of exact handles to fetch profiles directly. | | `teamId` | String | No | `""` | **Lichess Team ID.** Optional team slug (e.g., `titled-players` or `all-grandmasters`) to fetch members from. | | `maxItems` | Integer | Yes | `100` | **Maximum player records.** Hard limit on total player records scraped and saved to the dataset. | #### Example Input Configurations ##### 1. Top Grandmasters in Blitz ```json { "perfType": "blitz", "titleFilter": "GM", "minRating": 2700, "maxItems": 100 } ``` ##### 2. Top Norwegian Players in Bullet ```json { "perfType": "bullet", "countryFilter": "NO", "maxItems": 50 } ``` ##### 3. Specific Player Handles ```json { "usernames": ["DrNykterstein", "resemble", "Penguinim", "RebeccaHarris", "MagnusCarlsen"], "maxItems": 50 } ``` ##### 4. Official All-Grandmasters Team ```json { "teamId": "all-grandmasters", "maxItems": 200 } ``` *** ### ⬆️ Output Scraped player records are written directly to the run's default dataset. Each row represents a unique Lichess player entity identified by their addressable handle (`handle`). #### Dataset Schema Fields | Field Name | Type | Description | Example | | :--- | :--- | :--- | :--- | | `handle` | String | Unique Lichess player handle / username identifying the player entity. | `"DrNykterstein"` | | `username` | String | Display username of the Lichess account. | `"DrNykterstein"` | | `title` | String | Official FIDE or Lichess chess title (GM, WGM, IM, WIM, FM, WFM, CM, WCM, BOT). | `"GM"` | | `bulletRating` | Integer | Current Lichess rating in Bullet chess (1-minute / fast games). | `3243` | | `blitzRating` | Integer | Current Lichess rating in Blitz chess (3-5 minute games). | `3153` | | `rapidRating` | Integer | Current Lichess rating in Rapid chess (10+ minute games). | `2500` | | `classicalRating` | Integer | Current Lichess rating in Classical chess (long games). | `2500` | | `ultraBulletRating` | Integer | Current Lichess rating in UltraBullet chess (30-second games). | `2406` | | `chess960Rating` | Integer | Current Lichess rating in Chess960 / Fischer Random variant. | `2541` | | `crazyhouseRating` | Integer | Current Lichess rating in Crazyhouse variant. | `2756` | | `antichessRating` | Integer | Current Lichess rating in Antichess / Giveaway variant. | `2291` | | `atomicRating` | Integer | Current Lichess rating in Atomic variant. | `2465` | | `hordeRating` | Integer | Current Lichess rating in Horde variant. | `2890` | | `kingOfTheHillRating` | Integer | Current Lichess rating in King of the Hill variant. | `2836` | | `racingKingsRating` | Integer | Current Lichess rating in Racing Kings variant. | `2433` | | `threeCheckRating` | Integer | Current Lichess rating in Three-Check variant. | `2727` | | `totalGames` | Integer | Total number of games played across all Lichess variants. | `10435` | | `totalPlayTimeSeconds` | Integer | Cumulative total play time on Lichess in seconds. | `1169601` | | `country` | String | ISO two-letter country code set on user profile. | `"NO"` | | `profileName` | String | Real name or display name listed in user profile. | `"Magnus Carlsen"` | | `bio` | String | User profile biography snippet. | `"World Chess Champion"` | | `isPatron` | Boolean | Whether the user supports Lichess as a patron. | `true` | | `isVerified` | Boolean | Whether the Lichess account is officially verified. | `true` | | `createdAt` | String | ISO timestamp when the account was registered. | `"2018-12-06T12:44:50.814Z"` | | `seenAt` | String | ISO timestamp when the account was last active. | `"2026-08-03T18:00:00.000Z"` | | `url` | String | Canonical web URL to the player profile on Lichess. | `"https://lichess.org/@/DrNykterstein"` | #### Example Output Record ```json { "handle": "DrNykterstein", "username": "DrNykterstein", "title": "GM", "bulletRating": 3243, "blitzRating": 3153, "rapidRating": 2500, "classicalRating": 2500, "ultraBulletRating": 2406, "chess960Rating": 2541, "crazyhouseRating": 2756, "antichessRating": 2291, "atomicRating": 2465, "hordeRating": 2890, "kingOfTheHillRating": 2836, "racingKingsRating": 2433, "threeCheckRating": 2727, "totalGames": 10435, "totalPlayTimeSeconds": 1169601, "country": "NO", "profileName": "Magnus Carlsen", "bio": "World Chess Champion", "isPatron": true, "isVerified": true, "createdAt": "2018-12-06T12:44:50.814Z", "seenAt": "2026-08-03T18:00:00.000Z", "url": "https://lichess.org/@/DrNykterstein" } ``` *** ### Detailed Performance Variant Descriptions Lichess supports standard chess and eight non-standard chess variants. Each variant maintains an independent Glicko-2 rating system: 1. **Bullet**: Fast-paced chess games with time controls under 3 minutes per player (most commonly 1+0 or 2+1). 2. **Blitz**: Rapid-tactical chess games with time controls from 3 to 10 minutes per player (most commonly 3+0 or 5+0). 3. **Rapid**: Standard speed chess with time controls from 10 to 25 minutes per player (most commonly 10+0 or 15+10). 4. **Classical**: Slow time control chess with 25+ minutes per player. 5. **UltraBullet**: Extreme speed chess with 30-second total clock per player (0.5+0). 6. **Chess960 (Fischer Random)**: Shuffle chess invented by Bobby Fischer where starting piece positions on rank 1 and 8 are randomized. 7. **Crazyhouse**: Variant where captured enemy pieces change color and can be dropped onto any open square during your turn. 8. **Antichess (Giveaway)**: Variant where capturing is mandatory, kings have no royal powers, and the objective is to lose all pieces. 9. **Atomic**: Variant where capturing causes an explosion that destroys the capturing piece, captured piece, and adjacent non-pawn pieces within a 1-square radius. 10. **Horde**: Asymmetrical variant where White plays with 36 pawns against Black's standard army. 11. **King of the Hill**: Variant where moving your king to one of the four center squares (d4, d5, e4, e5) wins the game immediately. 12. **Racing Kings**: Variant where both players race their kings to the 8th rank without putting kings in check. 13. **Three-Check**: Variant where checking the opponent's king three times wins the game. *** ### How it works 1. **Player Discovery**: The actor connects to official Lichess API endpoints (`/api/player/top/200/{perf}`, `/api/team/{teamId}/users`, or direct input handles). 2. **Batch User Profiles**: Retrieves comprehensive user profile records in high-performance HTTP batches (`POST /api/users`), fetching ratings, play statistics, titles, countries, and profile bio data. 3. **Filtering**: Applies requested filters client-side (variant ratings, FIDE titles, country code, minimum/maximum rating thresholds). 4. **Pay-Per-Event Billing**: Charges exactly $0.002 per complete player record emitted to the default dataset (with tiered plan discounts down to $0.0008). Empty queries or rate-limited runs charge zero. 5. **Streaming Output**: Emits items continuously to the dataset in real-time as they are processed. *** ### Code Examples #### Python Integration (apify-client) ```python from apify_client import ApifyClient ## Initialize the ApifyClient with your API token client = ApifyClient("YOUR_API_TOKEN") ## Prepare the Actor input run_input = { "perfType": "blitz", "titleFilter": "GM", "countryFilter": "NO", "maxItems": 50 } ## Run the Actor and wait for it to finish run = client.actor("reapx/lichess-scraper").call(run_input=run_input) ## Fetch dataset items for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"{item['title']} {item['username']} - Blitz Rating: {item['blitzRating']}") ``` #### Node.js / JavaScript Integration (apify-client) ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_API_TOKEN', }); const input = { perfType: 'bullet', minRating: 2800, maxItems: 50, }; const run = await client.actor('reapx/lichess-scraper').call(input); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((player) => { console.log(`${player.handle} (${player.country || 'N/A'}): ${player.bulletRating}`); }); ``` #### cURL API Example ```bash curl -X POST "https://api.apify.com/v2/acts/reapx~lichess-scraper/runs?token=YOUR_API_TOKEN" -H "Content-Type: application/json" -d '{ "perfType": "chess960", "maxItems": 100 }' ``` *** ### ❓ FAQ #### 1. Does this scraper require a Lichess account or API key? No. All scraped endpoints are public open API surfaces provided by Lichess. No credentials or login cookies are required. #### 2. What game variants are supported? All 13 official Lichess performance categories are supported: Bullet, Blitz, Rapid, Classical, UltraBullet, Chess960 (Fischer Random), Crazyhouse, Antichess, Atomic, Horde, King of the Hill, Racing Kings, and Three-Check. #### 3. How does pricing work? This actor uses **Pay-Per-Event** pricing. You are charged $0.002 per player record returned to your dataset. Discounted pricing tiers apply automatically based on your Apify subscription (Bronze, Silver, Gold, Platinum, Diamond). If an invalid query or rate limit occurs and zero rows are returned, nothing is charged. #### 4. How often is Lichess data updated? Lichess leaderboards and user profiles update continuously in real-time as games complete on the platform. #### 5. Can I scrape members of a specific Lichess Team? Yes. Pass the team ID slug into the `teamId` parameter (e.g. `titled-players` or `all-grandmasters`). The scraper will stream the team members and fetch full profile details for each member. #### 6. How are missing profile fields handled? If a player has not configured a country code, biography, or real name, those fields will be returned as `null` in the dataset row without breaking schema structure. #### 7. What happens if a player account is closed or banned? Disabled or closed accounts returned by discovery endpoints are formatted with available metadata. If profile lookup fails for a handle, it is skipped without stopping the run. #### 8. Is rate limiting handled automatically? Yes. The scraper implements exponential backoff on HTTP 429 and HTTP 5xx responses, respecting Lichess server rate limit recommendations. #### 9. Can I export results to CSV or Excel? Yes. Apify Console allows exporting the run dataset in JSON, CSV, Excel, XML, or HTML formats with custom column selection. #### 10. Where can I inspect historical archive data? Extracted entity archives for this scraper are published and accessible at [reapx.dev/data/lichess-scraper/](https://reapx.dev/data/lichess-scraper/) and mirrored as open datasets on [Hugging Face](https://huggingface.co/datasets/reapxdev/lichess-scraper) and [Kaggle](https://www.kaggle.com/datasets/reapxdev/lichess-scraper). *** ### Use Cases & Applications - **Grandmaster & Master Analytics**: Track performance ratings of top GMs, IMs, and FMs across different speed chess formats. - **Chess Variant Research**: Compare player skills and rating distributions across standard chess vs Chess960, Crazyhouse, and Atomic variants. - **Tournament Scouting**: Prepare opponent data, favorite time controls, and total game counts for upcoming online tournaments. - **Bot Performance Monitoring**: Track rating progression and activity levels of official automated chess engines. - **Geographic Chess Demographics**: Analyze top player density and rating averages by country. *** ### 💬 Your feedback Have questions, feature requests, or custom extraction needs? Contact the maintainers directly at **reapxdev@proton.me**. *** *Unofficial - not affiliated with Lichess. Collects public data only. reapx. Contact reapxdev@proton.me.* ### 🧪 Example input A real, runnable configuration — this is an actual input this Actor has run with. ```json { "perfType": "bullet", "titleFilter": "all", "countryFilter": "", "minRating": 0, "maxRating": 4000, "maxItems": 100 } ``` ### 📄 Sample output One real row from a real run of this Actor, unedited. ```json { "handle": "mraquariyaz67", "username": "mraquariyaz67", "title": "GM", "bulletRating": 3502, "blitzRating": 3027, "rapidRating": 2797, "classicalRating": 1499, "ultraBulletRating": 3000, "chess960Rating": 2937, "crazyhouseRating": 2756, "antichessRating": 2291, "atomicRating": 2465, "hordeRating": 2890, "kingOfTheHillRating": 2836, "racingKingsRating": 2433, "threeCheckRating": 2727, "totalGames": 12966, "totalPlayTimeSeconds": 918241, "country": null, "profileName": null, "bio": null, "isPatron": false, "isVerified": false, "createdAt": "2025-10-26T23:29:56.115000+00:00", "seenAt": "2026-08-01T10:00:54.307000+00:00", "url": "https://lichess.org/@/mraquariyaz67" } ``` ### ⚠️ Run outcomes and error handling This Actor reports what happened in the run's **status message**, and it always keeps whatever it collected. These are the outcomes you can get and what each one means. | Outcome | What it means | |---|---| | **Success** | Rows were returned and you were charged `record-returned` at $0.002 per row. | | **No matches** | The source returned nothing for your filters. **Nothing is charged.** Widen the date window or drop a filter. | | **Partial - source refused** | The source rate-limited or refused some requests. The affected items are skipped and named in the log, and **everything already collected is still pushed**. A block never discards a run's work. | | **Rejected filter** | The source itself rejected the filter combination. The run fails fast with the source's own reason and **nothing is charged.** | #### What is guaranteed either way - **Every row is pushed as it is built**, not buffered to the end of the run. Anything that buffers output loses everything to a timeout, a block or a migration; this does not. - **A field absent from the source is absent from the row.** Nothing is inferred, modelled or filled in to make a row look complete. # Actor input Schema ## `perfType` (type: `string`): Game variant filter. Select the Lichess game mode or variant leaderboard to scrape top players from (e.g. bullet, blitz, rapid, classical, chess960, ultraBullet).

Consequence: Determines which leaderboard is scraped. Selecting 'all' checks leaderboards across all 13 supported variants.

Empty/Default: Defaults to bullet. ## `titleFilter` (type: `string`): Title filter. Filter player profiles by official FIDE or Lichess title (e.g., Grandmaster GM, Woman Grandmaster WGM, International Master IM, FIDE Master FM, or BOT).

Consequence: Restricts returned player rows to only accounts possessing the specified title.

Empty/Default: Leave as all to return all players regardless of title. ## `countryFilter` (type: `string`): Country filter. Filter players by their ISO two-letter country code (e.g. US, NO, IN, FR, DE, ES, RU, CN).

Consequence: Filters player profile results to players matching the given country.

Empty: Leave empty (default) to include players from all countries without restriction. ## `minRating` (type: `integer`): Minimum rating limit. Minimum rating threshold in the selected variant for players to be included in the dataset.

Consequence: Higher values filter out lower-rated players, reducing total rows returned and lowering run cost.

Empty/Default: Set to 0 for no minimum threshold. ## `maxRating` (type: `integer`): Maximum rating limit. Maximum rating ceiling for players to be included in the dataset.

Consequence: Excludes players rated above this threshold.

Empty/Default: Set to 4000 for no upper rating ceiling.

The higher the number, the longer the run takes and the more you are charged, because you pay per row returned. ## `usernames` (type: `array`): Target Lichess usernames. Specific Lichess handles/usernames to scrape directly.

Consequence: If provided, the scraper fetches full profile and game stats for these exact users instead of scanning leaderboards.

Empty: Leave empty (default) to discover top players via leaderboards. ## `teamId` (type: `string`): Lichess Team ID. Optional Lichess team ID (slug) to fetch members from (e.g. titled-players or all-grandmasters).

Consequence: Scrapes members belonging to the specified team.

Empty: Leave empty (default) to scrape main platform leaderboards. ## `maxItems` (type: `integer`): Maximum player records to return. Hard cap on the total number of player records scraped and returned in the dataset.

Consequence: The higher the limit, the longer the run takes and the more pay-per-event records are charged.

Empty/Default: Defaults to 100 players.

The higher the number, the longer the run takes and the more you are charged, because you pay per row returned. ## Actor input object example ```json { "perfType": "bullet", "titleFilter": "all", "minRating": 0, "maxRating": 4000, "maxItems": 100 } ``` # Actor output Schema ## `results` (type: `string`): Every player record found by this run, one row per player, in the default dataset. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "perfType": "bullet", "titleFilter": "all", "countryFilter": "", "teamId": "", "maxItems": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("reapx/lichess-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "perfType": "bullet", "titleFilter": "all", "countryFilter": "", "teamId": "", "maxItems": 100, } # Run the Actor and wait for it to finish run = client.actor("reapx/lichess-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "perfType": "bullet", "titleFilter": "all", "countryFilter": "", "teamId": "", "maxItems": 100 }' | apify call reapx/lichess-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,reapx/lichess-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/0B56agqBrnMtrda2T/builds/P09ddsYEMyXw0A2aO/openapi.json