# HowLongToBeat Scraper (`crawlerbros/howlongtobeat-scraper`) Actor Scrape HowLongToBeat.com - the world's largest database of game completion times. Get Main Story, Main + Extra, Completionist and All Styles hours for any game. Supports lookup by game ID and browsing popular games. - **URL**: https://apify.com/crawlerbros/howlongtobeat-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Developer tools, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use 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 ## HowLongToBeat Scraper Extract game completion time data from [HowLongToBeat.com](https://howlongtobeat.com) — the internet's most trusted source for how long it takes to beat video games. ### What Does This Scraper Do? This actor fetches detailed completion time information for video games from HowLongToBeat.com, including: - **Main Story** hours — time to complete the primary storyline - **Main + Extras** hours — main story plus major side content - **Completionist** hours — 100% completion time - **All Styles** hours — median across all playstyles - **Speedrun / Speedrun 100%** hours (mode=byId) — fastest recorded completion times - **Co-op / Multiplayer** hours — time invested in cooperative or multiplayer modes - Game metadata: developer, publisher, platforms, genres, release year, regional release dates, alternate titles/editions - Community data: player ratings, review counts, backlog/playing/retired/replay counts - Cover art image URLs ### Modes #### `byId` — Lookup by HLTB Game ID Fetch detailed game data using HowLongToBeat's numeric game IDs. Find game IDs in the URL when browsing HLTB (e.g., `howlongtobeat.com/game/10270` → ID is `10270`). **Popular game IDs (verified):** - `10270` — The Witcher 3: Wild Hunt - `68151` — Elden Ring - `2127` — Cyberpunk 2077 - `27100` — Red Dead Redemption 2 - `26286` — Hollow Knight For any other game, look up its ID by searching for the title on howlongtobeat.com and reading the number from the resulting game page's URL — HLTB's numeric IDs are reassigned occasionally, so don't hardcode IDs from third-party lists without verifying them first. #### `search` — Search Games by Name Free-text search across HLTB's full game database by title or keyword (e.g. `zelda`, `final fantasy`, `portal`). Supports sorting via `sortBy` (popularity, alphabetical, most currently playing, highest rating, newest release, largest backlog). #### `popular` — Browse Trending Games Returns the current popular/trending titles from the HowLongToBeat homepage. ### Input Parameters | Parameter | Type | Description | |-----------|------|-------------| | `mode` | String | `byId`, `search`, or `popular` | | `gameIds` | Array | HLTB numeric game IDs (mode=byId) | | `searchQuery` | String | Game name/keyword to search for (mode=search, required) | | `sortBy` | String | Sort order for search results — `popular` (default), `name`, `playing`, `rating`, `release`, or `backlog` (mode=search) | | `maxItems` | Integer | Maximum records to return (default: 20) | ### Output Fields Each record contains: | Field | Type | Description | |-------|------|-------------| | `gameId` | Integer | HowLongToBeat numeric game ID | | `title` | String | Game title | | `description` | String | Short game description | | `developer` | String | Game developer | | `publisher` | String | Game publisher | | `platforms` | Array | List of platforms (PC, PS5, Xbox, etc.) | | `genres` | Array | Game genres (Action, RPG, etc.) | | `releaseYear` | Integer | Year of worldwide release | | `mainStoryHours` | Float | Hours to complete main story | | `mainPlusExtrasHours` | Float | Hours for main story + extras | | `completionistHours` | Float | Hours for 100% completion | | `allStylesHours` | Float | Median hours across all playstyles | | `speedrunHours` | Float | Fastest recorded main-story speedrun time (mode=byId) | | `speedrun100Hours` | Float | Fastest recorded 100% speedrun time (mode=byId) | | `speedrunSubmissions` | Integer | Number of speedrun time submissions | | `coOpHours` | Float | Hours invested in cooperative play | | `coOpSubmissions` | Integer | Number of co-op time submissions | | `multiplayerHours` | Float | Hours invested in multiplayer/competitive play | | `multiplayerSubmissions` | Integer | Number of multiplayer time submissions | | `totalSubmissions` | Integer | Sum of main/main+extras/completionist/all-styles submissions | | `allSubmissionsCount` | Integer | HLTB's authoritative grand-total submissions across every category (mode=byId) | | `rating` | Integer | Community rating score (0-100) | | `reviewCount` | Integer | Number of community reviews | | `countPlaying` | Integer | Players currently playing | | `countBacklog` | Integer | Players with game in backlog | | `countCompleted` | Integer | Players who completed the game | | `retiredCount` | Integer | Players who retired (gave up on) the game | | `replayCount` | Integer | Players who replayed the game (mode=byId) | | `customCount` | Integer | Custom-category time submissions (mode=byId) | | `discussionCount` | Integer | Number of discussion posts about the game (mode=byId) | | `popularityRank` | Integer | HLTB popularity ranking score (mode=search/popular) | | `alternateNames` | Array | Alternate titles, regional editions, or re-release names | | `releaseDateNA` | String | North America release date, `YYYY-MM-DD` (mode=byId) | | `releaseDateEU` | String | Europe release date, `YYYY-MM-DD` (mode=byId) | | `releaseDateJP` | String | Japan release date, `YYYY-MM-DD` (mode=byId) | | `parentGameId` | Integer | Base game's HLTB ID, present for DLC/expansions (mode=byId) | | `imageUrl` | String | Game cover art URL | | `steamId` | Integer | Steam app ID (if available) | | `gameType` | String | Type classification (game, dlc, etc.) | | `ratingEsrb` | String | ESRB age rating | | `ratingPegi` | String | PEGI age rating | | `ratingCero` | String | CERO (Japan) age rating (mode=byId) | | `gameUrl` | String | Full URL to HLTB game page | | `sourceUrl` | String | URL that was scraped | | `scrapedAt` | String | ISO 8601 timestamp | | `recordType` | String | Always `game` | > **Mode note:** fields tagged _(mode=byId)_ come only from a game's detail page. The `search` and `popular` modes use HowLongToBeat's lighter list API, which — on top of the tagged fields — also omits `description`, `developer`, `publisher`, `genres`, `gameType`, `ratingEsrb`, `ratingPegi`, `totalSubmissions` and `countCompleted`. Every record includes `gameId`, so you can follow up with a `byId` lookup to retrieve the full field set. ### Example Output ```json { "gameId": 10270, "title": "The Witcher 3: Wild Hunt", "developer": "CD Projekt Red", "publisher": "CD Projekt", "platforms": ["PC", "PlayStation 4", "PlayStation 5", "Xbox One", "Xbox Series X/S"], "genres": ["Action", "RPG"], "releaseYear": 2015, "mainStoryHours": 51.6, "mainPlusExtrasHours": 84.4, "completionistHours": 139.1, "allStylesHours": 71.7, "rating": 95, "reviewCount": 8000, "speedrunHours": 11.0, "speedrunSubmissions": 42, "allSubmissionsCount": 120000, "retiredCount": 900, "releaseDateNA": "2015-05-19", "releaseDateEU": "2015-05-19", "releaseDateJP": "2015-05-19", "alternateNames": ["The Witcher 3: Wild Hunt - Game of the Year Edition"], "steamId": 292030, "imageUrl": "https://howlongtobeat.com/games/Witcher3_1_large.png", "gameUrl": "https://howlongtobeat.com/game/10270", "sourceUrl": "https://howlongtobeat.com/game/10270", "scrapedAt": "2026-06-30T12:00:00+00:00", "recordType": "game" } ```` ### Use Cases - **Gaming backlog management** — prioritize games by completion time - **Gaming journalism** — research articles about game lengths - **Game recommendation systems** — filter by playtime preference - **Market research** — analyze completion rates across genres and platforms - **Game length comparisons** — compare franchises and sequels ### Finding Game IDs 1. Go to [howlongtobeat.com](https://howlongtobeat.com) 2. Search for any game 3. Click on the game to open its detail page 4. The ID is the number in the URL: `howlongtobeat.com/game/**10270**` ### FAQ **Q: Why is a game missing completion time data?** A: Some games (multiplayer-only, very new, or niche titles) may have few or no submissions. HowLongToBeat requires user submissions to calculate averages. **Q: What does "All Styles" mean?** A: This is the median playtime across all submission types — it represents a typical playthrough regardless of how much extra content was completed. **Q: How often is the data updated?** A: HowLongToBeat updates in real-time as users submit their playtimes. Each scrape reflects the current averages. **Q: Can I scrape all games at once?** A: Use the `byId` mode with a list of game IDs. HowLongToBeat game IDs are sequential integers, so you can enumerate ranges if needed. **Q: Can I search for games by name instead of looking up IDs manually?** A: Yes — use `mode=search` with `searchQuery` set to any game title or keyword. This is the easiest way to find games without needing to know their HLTB ID upfront, and results include the `gameId` for follow-up `byId` lookups if you need the full detail-page fields (speedrun times, regional release dates, etc.). **Q: What is the difference between Main Story and Completionist?** A: Main Story is the minimum time to finish the primary narrative. Completionist includes all achievements, collectibles, side quests, and optional content to reach 100%. # Actor input Schema ## `mode` (type: `string`): What to scrape: `byId` fetches a single game by its HLTB numeric ID, `search` finds games by name, `popular` returns trending titles from the homepage. ## `gameIds` (type: `array`): List of HowLongToBeat numeric game IDs. Example: `10270` for The Witcher 3, `68151` for Elden Ring. ## `searchQuery` (type: `string`): Game name or keyword to search for, e.g. 'zelda', 'final fantasy'. Required for mode=search. ## `sortBy` (type: `string`): Sort order for search results (only applies when mode=search). HLTB's default is Popularity. ## `maxItems` (type: `integer`): Maximum number of game records to emit. ## Actor input object example ```json { "mode": "byId", "gameIds": [ "10270" ], "searchQuery": "zelda", "sortBy": "popular", "maxItems": 20 } ``` # Actor output Schema ## `games` (type: `string`): Dataset containing all scraped game records with completion time breakdowns. # 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 = { "mode": "byId", "gameIds": [ "10270" ], "searchQuery": "zelda", "sortBy": "popular", "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/howlongtobeat-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 = { "mode": "byId", "gameIds": ["10270"], "searchQuery": "zelda", "sortBy": "popular", "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/howlongtobeat-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "byId", "gameIds": [ "10270" ], "searchQuery": "zelda", "sortBy": "popular", "maxItems": 20 }' | apify call crawlerbros/howlongtobeat-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/howlongtobeat-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "HowLongToBeat Scraper", "description": "Scrape HowLongToBeat.com - the world's largest database of game completion times. Get Main Story, Main + Extra, Completionist and All Styles hours for any game. Supports lookup by game ID and browsing popular games.", "version": "1.0", "x-build-id": "zdrmESpMhM9RoQ1B4" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~howlongtobeat-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-howlongtobeat-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~howlongtobeat-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-howlongtobeat-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~howlongtobeat-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-howlongtobeat-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "byId", "search", "popular" ], "type": "string", "description": "What to scrape: `byId` fetches a single game by its HLTB numeric ID, `search` finds games by name, `popular` returns trending titles from the homepage.", "default": "byId" }, "gameIds": { "title": "Game IDs (mode=byId)", "type": "array", "description": "List of HowLongToBeat numeric game IDs. Example: `10270` for The Witcher 3, `68151` for Elden Ring.", "default": [ "10270" ], "items": { "type": "string" } }, "searchQuery": { "title": "Search query (mode=search)", "type": "string", "description": "Game name or keyword to search for, e.g. 'zelda', 'final fantasy'. Required for mode=search." }, "sortBy": { "title": "Sort by (mode=search)", "enum": [ "popular", "name", "playing", "rating", "release", "backlog" ], "type": "string", "description": "Sort order for search results (only applies when mode=search). HLTB's default is Popularity.", "default": "popular" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of game records to emit.", "default": 20 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```