# Speedrun.com Leaderboard & Runs Scraper (`jungle_synthesizer/speedrun-com-leaderboard-runs-scraper`) Actor Scrape speedrun.com leaderboard rankings for any game and category. Resolves game names to IDs, enumerates categories automatically, and returns flattened run rows with player names, times, ranks, WR flags, platform, region, and video links via the official v1 REST API. - **URL**: https://apify.com/jungle\_synthesizer/speedrun-com-leaderboard-runs-scraper.md - **Developed by:** [BowTiedRaccoon](https://apify.com/jungle_synthesizer) (community) - **Categories:** Games, Sports - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 ## Speedrun.com Leaderboard & Runs Scraper Scrape leaderboard rankings and verified run records from [speedrun.com](https://www.speedrun.com) for any game and category. The actor resolves game names to IDs automatically, enumerates categories, and returns flat run records with player names, times, ranks, world-record flags, platform, region, subcategory labels, and video links — all via the official speedrun.com v1 REST API. ### What you get Each output record represents one verified run on a speedrun.com leaderboard: | Field | Description | |-------|-------------| | `game_id` | speedrun.com internal game ID | | `game_name` | Game title (international) | | `game_abbreviation` | URL slug, e.g. `sm64` | | `game_released_year` | Year of release | | `category_id` | speedrun.com category ID | | `category_name` | Category label, e.g. `120 Star`, `Any%` | | `subcategory_variables` | Pipe-separated subcategory variable labels, e.g. `Platform:N64` | | `run_id` | Unique run identifier | | `rank` | Leaderboard position (1 = current world record) | | `is_world_record` | `true` when `rank` equals 1 | | `primary_time_seconds` | Timed duration in seconds | | `player_ids` | Pipe-separated player IDs | | `player_names` | Pipe-separated player display names | | `player_country` | ISO 3166-1 alpha-2 country code of the first player | | `platform` | Platform name, e.g. `Nintendo 64`, `PC` | | `emulated` | `true` if the run used an emulator | | `region` | Region label, e.g. `JPN / NTSC` | | `run_date` | Date the run was performed (`YYYY-MM-DD`) | | `verify_date` | ISO-8601 timestamp when the run was verified | | `video_link` | Primary video URL (YouTube, Twitch, etc.) | | `comment` | Runner-submitted comment | | `examiner_id` | ID of the verifier who approved the run | | `weblink` | Direct URL to this run on speedrun.com | ### Input | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `gameQuery` | string | — | Game name or abbreviation to search. Partial names work (e.g. `super mario 64`, `sm64`). | | `categoryName` | string | (all) | Optional filter. Leave blank to scrape all per-game categories. | | `topN` | integer | 20 | Maximum top runs to fetch per leaderboard (1–200). | | `maxItems` | integer | 10 | Total output cap across all leaderboards. | #### Example: Top 10 runs in SM64 "120 Star" ```json { "gameQuery": "super mario 64", "categoryName": "120 Star", "topN": 10, "maxItems": 10 } ```` #### Example: All categories for Minecraft Java Edition ```json { "gameQuery": "minecraft: java edition", "topN": 5, "maxItems": 100 } ``` ### How it works 1. **Game resolution** — Searches by abbreviation (exact) then by name (up to 5 matches). This is the step naive slug-guessing misses — the API returns 404 on unresolved IDs. 2. **Category enumeration** — Fetches per-game categories for each matched game, optionally filtered by `categoryName`. 3. **Subcategory labels** — Resolves category-specific variables with `is-subcategory: true` to human-readable labels (e.g. `Platform:N64 | Version:1.0`). 4. **Leaderboard fetch** — One request per game+category with `?embed=players,platforms,regions` to resolve all IDs in-response without additional calls. ### Rate limits speedrun.com allows approximately 100 requests per minute unauthenticated. The actor throttles to one request per 600 ms and retries on 429 responses with exponential backoff. ### Use cases - Track world record holders and submission history for esports analytics - Monitor game leaderboards for creator tooling and Discord bots - Aggregate speedrun data across games for data journalism and community dashboards - Compare subcategory breakdowns (console vs. emulator, version splits) # Actor input Schema ## `sp_intended_usage` (type: `string`): Please describe how you plan to use the data extracted by this crawler. ## `sp_improvement_suggestions` (type: `string`): Provide any feedback or suggestions for improvements. ## `sp_contact` (type: `string`): Provide your email address so we can get in touch with you. ## `gameQuery` (type: `string`): Name or exact speedrun.com game ID to search. Partial names work (e.g. "super mario 64"). Use the game's abbreviation for exact matches (e.g. "sm64"). ## `categoryName` (type: `string`): Optional category name to filter (e.g. "120 Star", "Any%"). Leave blank to scrape all per-game categories. ## `topN` (type: `integer`): Maximum number of top runs to fetch per game/category combination. Valid range 1–200. Defaults to 20. ## `maxItems` (type: `integer`): Maximum total number of run records to output across all leaderboards. ## Actor input object example ```json { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "gameQuery": "super mario 64", "topN": 20, "maxItems": 10 } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 = { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "gameQuery": "super mario 64", "topN": 20, "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("jungle_synthesizer/speedrun-com-leaderboard-runs-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 = { "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "gameQuery": "super mario 64", "topN": 20, "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("jungle_synthesizer/speedrun-com-leaderboard-runs-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 '{ "sp_intended_usage": "Describe your intended use...", "sp_improvement_suggestions": "Share your suggestions here...", "sp_contact": "Share your email here...", "gameQuery": "super mario 64", "topN": 20, "maxItems": 10 }' | apify call jungle_synthesizer/speedrun-com-leaderboard-runs-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=jungle_synthesizer/speedrun-com-leaderboard-runs-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Speedrun.com Leaderboard & Runs Scraper", "description": "Scrape speedrun.com leaderboard rankings for any game and category. Resolves game names to IDs, enumerates categories automatically, and returns flattened run rows with player names, times, ranks, WR flags, platform, region, and video links via the official v1 REST API.", "version": "0.1", "x-build-id": "uWkiutaCwEKdrwJhJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jungle_synthesizer~speedrun-com-leaderboard-runs-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jungle_synthesizer-speedrun-com-leaderboard-runs-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/jungle_synthesizer~speedrun-com-leaderboard-runs-scraper/runs": { "post": { "operationId": "runs-sync-jungle_synthesizer-speedrun-com-leaderboard-runs-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/jungle_synthesizer~speedrun-com-leaderboard-runs-scraper/run-sync": { "post": { "operationId": "run-sync-jungle_synthesizer-speedrun-com-leaderboard-runs-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": [ "gameQuery", "maxItems" ], "properties": { "sp_intended_usage": { "title": "What is the intended usage of this data?", "minLength": 1, "type": "string", "description": "Please describe how you plan to use the data extracted by this crawler." }, "sp_improvement_suggestions": { "title": "How can we improve this crawler for you?", "minLength": 1, "type": "string", "description": "Provide any feedback or suggestions for improvements." }, "sp_contact": { "title": "Contact Email", "minLength": 1, "type": "string", "description": "Provide your email address so we can get in touch with you." }, "gameQuery": { "title": "Game Name or ID", "type": "string", "description": "Name or exact speedrun.com game ID to search. Partial names work (e.g. \"super mario 64\"). Use the game's abbreviation for exact matches (e.g. \"sm64\")." }, "categoryName": { "title": "Category Filter", "type": "string", "description": "Optional category name to filter (e.g. \"120 Star\", \"Any%\"). Leave blank to scrape all per-game categories." }, "topN": { "title": "Top N Runs Per Leaderboard", "type": "integer", "description": "Maximum number of top runs to fetch per game/category combination. Valid range 1–200. Defaults to 20.", "default": 20 }, "maxItems": { "title": "Max Items", "type": "integer", "description": "Maximum total number of run records to output across all leaderboards.", "default": 10 } } }, "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 } } } } } } } } } } ```