# Royal Road Scraper (`crawlerbros/royalroad-scraper`) Actor Scrape Royal Road - the leading platform for serialized web fiction (progression fantasy, LitRPG, GameLit). Browse curated lists, search by genre/tag/status, fetch full fiction details with chapter lists, or list an author's fictions. No login required. - **URL**: https://apify.com/crawlerbros/royalroad-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 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/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 ## Royal Road Scraper Scrape **Royal Road** — the leading platform for serialized web fiction (progression fantasy, LitRPG, GameLit, portal fantasy, and more). Browse any of Royal Road's 9 curated fiction lists, run advanced search with genre/tag/status/rating filters, fetch full fiction details with the complete chapter list, or pull every fiction published by a specific author. HTTP-only and fully public — no login, no cookies, no API key, and no proxy required. ### What this actor does - **Four modes:** `browse` (curated lists), `search` (advanced filters), `fictionDetail` (full detail + chapter list by URL/ID), `byAuthor` (all fictions by an author) - **9 curated lists:** Best Rated, Trending, Ongoing Fictions, Complete, Popular This Week, Latest Updates, Newest, Rising Stars, Writathon — plus genre-specific Rising Stars rankings (~50 fictions per genre) - **Full filter set:** 16 genres, 72 secondary tags, 6 content warnings, status, fiction type, page-count range, rating range, 10 sort orders - **Chapter lists:** every chapter's title, URL, publish date, and free/premium flag (chapter body text is not included — see FAQ) - **Empty fields are omitted** — a record never contains `null`, `""`, or `[]` ### Output per fiction **Always present:** `fictionId`, `title`, `sourceUrl`, `recordType: "fiction"`, `scrapedAt` **Present when available (browse / search / byAuthor):** - `slug`, `coverUrl` - `fictionType` (`Original` / `Fan Fiction`), `status` (`ONGOING` / `COMPLETED` / `HIATUS` / `STUB` / `DROPPED` / `INACTIVE`) - `genres[]`, `tags[]`, `contentWarnings[]` - `followers`, `rating` (0–5), `pages`, `views`, `chapterCount`, `lastUpdated`, `description` **Present when available (fictionDetail — full record):** - `authorName`, `authorId`, `authorUrl` - `overallScore`, `styleScore`, `storyScore`, `grammarScore`, `characterScore` (each 0–5) - `totalViews`, `averageViews`, `followers`, `favorites`, `ratingsCount`, `pages`, `wordCount` - `language` (e.g. `en-US`), `publishedAt` (original publish date), `lastUpdated` (last chapter date), `isFree` (whether the fiction is currently fully free to read) - `chapterCount`, `firstChapterUrl` - `chapters[]` — each with `chapterId`, `title`, `url`, `order`, `publishedAt`, `isFree` **Present when available (byAuthor):** - `authorId`, `authorUrl`, `authorName`, `authorAvatarUrl` attached to every fiction record - `authorJoinedAt`, `authorLastActive` — from the author's public profile page - `authorGender`, `authorLocation`, `authorBio` — only when the author has filled these in on their public profile - `authorFollowsCount`, `authorFavoritesCount`, `authorReviewsCount`, `authorFictionsCount` — the author's own public activity counters ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | `browse` | `browse` / `search` / `fictionDetail` / `byAuthor` | | `listType` | string | `bestRated` | Curated list to scrape (mode=browse) | | `risingStarsGenre` | string | – | Restrict `listType=risingStars` to a single genre's ranking (mode=browse) | | `searchTitle` | string | – | Title contains (mode=search) | | `searchKeyword` | string | `dungeon` | Free-text keyword (mode=search) | | `searchAuthor` | string | – | Author name contains (mode=search) | | `genres` | array | – | Genre filter, up to 16 values (mode=search) | | `tags` | array | – | Secondary tag filter, up to 72 values (mode=search) | | `contentWarnings` | array | – | Content warning filter, up to 6 values (mode=search) | | `excludeTags` | array | – | Exclude genres/tags/warnings (mode=search) | | `status` | array | – | Status filter — leave empty for all statuses (mode=search) | | `fictionType` | string | `ALL` | `ALL` / `original` / `fanfiction` (mode=search) | | `minPages` / `maxPages` | int | – | Estimated printed-book page range, 0–20000 (mode=search) | | `minRating` / `maxRating` | number | – | Overall rating range, 0–5 (mode=search) | | `orderBy` | string | `relevance` | Sort field (mode=search) | | `sortDirection` | string | `desc` | `asc` / `desc` (mode=search) | | `fictionUrls` | array | – | Fiction URLs or numeric IDs (mode=fictionDetail) | | `authorUrls` | array | – | Author profile URLs or numeric IDs (mode=byAuthor) | | `maxItems` | int | `25` | Hard cap on emitted records (1–1000) | | `proxy` | object | AUTO | Apify proxy (datacenter AUTO group); used only as an automatic fallback if requests start getting blocked | #### Example: browse the Rising Stars list ```json { "mode": "browse", "listType": "risingStars", "maxItems": 50 } ```` #### Example: genre-specific Rising Stars (LitRPG-adjacent Fantasy) ```json { "mode": "browse", "listType": "risingStars", "risingStarsGenre": "fantasy", "maxItems": 50 } ``` #### Example: search for ongoing LitRPG with a high rating ```json { "mode": "search", "genres": ["fantasy"], "tags": ["litrpg", "progression"], "status": ["ONGOING"], "minRating": 4.0, "maxItems": 50 } ``` #### Example: full detail + chapter list for specific fictions ```json { "mode": "fictionDetail", "fictionUrls": [ "https://www.royalroad.com/fiction/21220/mother-of-learning", "76354" ] } ``` #### Example: every fiction by an author ```json { "mode": "byAuthor", "authorUrls": ["https://www.royalroad.com/profile/100374"] } ``` ### Use cases - **Reader discovery tools** — build recommendation feeds from Royal Road's curated lists and tag taxonomy - **Market research** — track which genres/tags are trending among progression-fantasy and LitRPG readers - **Author analytics** — monitor a specific author's catalog, ratings, and update cadence - **Content aggregators** — mirror fiction metadata (title, description, chapter list, cover art) for a directory site - **Competitive intelligence for indie publishing** — benchmark word counts, follower counts, and ratings across a genre ### FAQ **What is the data source?** The public royalroad.com website. No API key, login, or cookies are required — all data comes from publicly viewable pages. **Is chapter body text included?** No. This actor returns chapter *metadata* only (title, URL, publish date, free/premium flag). Fetching full chapter text is a much heavier scrape and out of scope for this actor. **Are "related/recommended fictions" included on `fictionDetail`?** No. Royal Road renders its recommendations widget via a client-side AJAX call after page load (`
` is empty in the raw HTML) — it isn't present in the static page this actor fetches, so it can't be reliably scraped without a full browser. Everything else on the fiction detail page (stats, scores, tags, chapters, JSON-LD dates/language) is present in the static HTML and is fully covered. **What's the difference between `genres` and `tags`?** Royal Road treats "genres" (16 broad categories like Fantasy, Sci-fi, Romance) as a subset of its full tag vocabulary. "Tags" here covers the other ~72 more specific descriptors (LitRPG, Dungeon Core, Time Loop, etc.). Both are searchable the same way on Royal Road; this actor separates them into two dropdowns purely for a cleaner input UI. **Why do `Trending` and `Rising Stars` cap around 50 results even with a higher `maxItems`?** Those two lists are fixed-size algorithmic rankings on Royal Road itself (no further pages exist) — this is a genuine source limitation, not an actor bug. Every other list (`Best Rated`, `Complete`, `Latest Updates`, etc.) paginates fully. **What is `risingStarsGenre`?** Royal Road publishes a separate Rising Stars ranking (~50 fictions) for each of its 16 genres, in addition to the overall cross-genre list. Set `listType=risingStars` and pick a `risingStarsGenre` to fetch a genre-specific ranking instead of the overall one. **Why is `Writathon` sometimes empty?** It's a seasonal event list tied to Royal Road's periodic writing challenges. Outside an active event window it may return zero results. **Why is `contentWarnings` almost always empty in the output, even when I filter by it?** The `contentWarnings` search filter genuinely works server-side — filtering by e.g. "Graphic Violence" returns only fictions Royal Road has flagged with that warning. However, Royal Road does not render content-warning tags as visible links on its fiction listing cards or detail pages (unlike genres and regular tags, which are always shown) — this is how Royal Road's own site is built, not a limitation of this actor. The `contentWarnings` output field will populate only on the rare fiction where Royal Road happens to also show it as a regular tag. **Are ratings out of 5?** Yes — `rating` (listing pages) and `overallScore`/`styleScore`/`storyScore`/`grammarScore`/`characterScore` (fiction detail) are all on Royal Road's native 0–5 scale. **Is this affiliated with Royal Road?** No. This is an independent third-party actor that reads Royal Road's public pages. **Does this actor need a proxy?** No — it works from Apify's standard datacenter IPs. A proxy field is exposed only as an automatic fallback if Royal Road ever starts rate-limiting a specific run. # Actor input Schema ## `mode` (type: `string`): What to fetch. ## `listType` (type: `string`): Which curated Royal Road list to scrape. ## `risingStarsGenre` (type: `string`): Optional. Royal Road publishes a separate Rising Stars ranking (~50 fictions) for each genre. Leave blank for the overall cross-genre Rising Stars list. ## `searchTitle` (type: `string`): Match fictions whose title contains this text. ## `searchKeyword` (type: `string`): Free-text keyword search across title and description. ## `searchAuthor` (type: `string`): Match fictions by a specific author name. ## `genres` (type: `array`): Only include fictions tagged with at least one of these genres. ## `tags` (type: `array`): Only include fictions tagged with at least one of these secondary tags. ## `contentWarnings` (type: `array`): Only include fictions flagged with at least one of these content warnings. ## `excludeTags` (type: `array`): Exclude fictions tagged with any of these genres, tags, or content warnings. ## `status` (type: `array`): Only include fictions with one of these statuses. Leave empty for all statuses. ## `fictionType` (type: `string`): Filter by original work vs fan fiction. ## `minPages` (type: `integer`): Minimum estimated printed-book page count (275 words/page). ## `maxPages` (type: `integer`): Maximum estimated printed-book page count (275 words/page). ## `minRating` (type: `number`): Minimum overall rating, 0-5. ## `maxRating` (type: `number`): Maximum overall rating, 0-5. ## `orderBy` (type: `string`): Sort order for search results. ## `sortDirection` (type: `string`): Ascending or descending sort order. ## `fictionUrls` (type: `array`): Royal Road fiction URLs (e.g. https://www.royalroad.com/fiction/21220/mother-of-learning) or bare numeric fiction IDs. ## `authorUrls` (type: `array`): Royal Road author profile URLs (e.g. https://www.royalroad.com/profile/100374) or bare numeric profile IDs. ## `maxItems` (type: `integer`): Hard cap on emitted records. ## `proxy` (type: `object`): Optional. Royal Road works from Apify datacenter IPs without any proxy at all. Leave disabled (default) to avoid proxy usage entirely; only enable if you start seeing 403/429 errors from Royal Road. ## Actor input object example ```json { "mode": "browse", "listType": "bestRated", "risingStarsGenre": "", "searchKeyword": "dungeon", "genres": [], "tags": [], "contentWarnings": [], "excludeTags": [], "status": [], "fictionType": "ALL", "orderBy": "relevance", "sortDirection": "desc", "fictionUrls": [ "https://www.royalroad.com/fiction/21220/mother-of-learning" ], "authorUrls": [ "https://www.royalroad.com/profile/100374" ], "maxItems": 25, "proxy": { "useApifyProxy": false } } ``` # Actor output Schema ## `fictions` (type: `string`): Dataset containing all scraped Royal Road fictions. # 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": "browse", "listType": "bestRated", "risingStarsGenre": "", "searchKeyword": "dungeon", "genres": [], "tags": [], "contentWarnings": [], "excludeTags": [], "status": [], "fictionType": "ALL", "orderBy": "relevance", "sortDirection": "desc", "fictionUrls": [ "https://www.royalroad.com/fiction/21220/mother-of-learning" ], "authorUrls": [ "https://www.royalroad.com/profile/100374" ], "maxItems": 25, "proxy": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/royalroad-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": "browse", "listType": "bestRated", "risingStarsGenre": "", "searchKeyword": "dungeon", "genres": [], "tags": [], "contentWarnings": [], "excludeTags": [], "status": [], "fictionType": "ALL", "orderBy": "relevance", "sortDirection": "desc", "fictionUrls": ["https://www.royalroad.com/fiction/21220/mother-of-learning"], "authorUrls": ["https://www.royalroad.com/profile/100374"], "maxItems": 25, "proxy": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/royalroad-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": "browse", "listType": "bestRated", "risingStarsGenre": "", "searchKeyword": "dungeon", "genres": [], "tags": [], "contentWarnings": [], "excludeTags": [], "status": [], "fictionType": "ALL", "orderBy": "relevance", "sortDirection": "desc", "fictionUrls": [ "https://www.royalroad.com/fiction/21220/mother-of-learning" ], "authorUrls": [ "https://www.royalroad.com/profile/100374" ], "maxItems": 25, "proxy": { "useApifyProxy": false } }' | apify call crawlerbros/royalroad-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/royalroad-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Royal Road Scraper", "description": "Scrape Royal Road - the leading platform for serialized web fiction (progression fantasy, LitRPG, GameLit). Browse curated lists, search by genre/tag/status, fetch full fiction details with chapter lists, or list an author's fictions. No login required.", "version": "1.0", "x-build-id": "omVREVgGIZ3VHzq8b" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~royalroad-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-royalroad-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~royalroad-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-royalroad-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~royalroad-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-royalroad-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": [ "browse", "search", "fictionDetail", "byAuthor" ], "type": "string", "description": "What to fetch.", "default": "browse" }, "listType": { "title": "Curated list (mode=browse)", "enum": [ "bestRated", "trending", "activePopular", "complete", "weeklyPopular", "latestUpdates", "new", "risingStars", "writathon" ], "type": "string", "description": "Which curated Royal Road list to scrape.", "default": "bestRated" }, "risingStarsGenre": { "title": "Rising Stars genre filter (listType=risingStars)", "enum": [ "", "action", "adventure", "comedy", "contemporary", "drama", "fantasy", "historical", "horror", "mystery", "psychological", "romance_main", "satire", "sci_fi", "one_shot", "thriller", "tragedy" ], "type": "string", "description": "Optional. Royal Road publishes a separate Rising Stars ranking (~50 fictions) for each genre. Leave blank for the overall cross-genre Rising Stars list.", "default": "" }, "searchTitle": { "title": "Title contains (mode=search)", "type": "string", "description": "Match fictions whose title contains this text." }, "searchKeyword": { "title": "Keyword (mode=search)", "type": "string", "description": "Free-text keyword search across title and description.", "default": "dungeon" }, "searchAuthor": { "title": "Author name contains (mode=search)", "type": "string", "description": "Match fictions by a specific author name." }, "genres": { "title": "Genres (mode=search)", "type": "array", "description": "Only include fictions tagged with at least one of these genres.", "items": { "type": "string", "enum": [ "action", "adventure", "comedy", "contemporary", "drama", "fantasy", "historical", "horror", "mystery", "psychological", "romance_main", "satire", "sci_fi", "one_shot", "thriller", "tragedy" ], "enumTitles": [ "Action", "Adventure", "Comedy", "Contemporary", "Drama", "Fantasy", "Historical", "Horror", "Mystery", "Psychological", "Romance", "Satire", "Sci-fi", "Short Story", "Thriller", "Tragedy" ] }, "default": [] }, "tags": { "title": "Tags (mode=search)", "type": "array", "description": "Only include fictions tagged with at least one of these secondary tags.", "items": { "type": "string", "enum": [ "anti-hero_lead", "antivillain_lead", "apocalypse", "artificial_intelligence", "attractive_lead", "chivalry", "competing_love", "cozy", "crafting", "cultivation", "cyberpunk", "deck_building", "dungeon_core", "dungeon_crawler", "dystopia", "female_lead", "first_contact", "gamelit", "gender_bender", "genetically_engineered", "grimdark", "hard_sci-fi", "high_fantasy", "kingdom_building", "lesbian_romance", "litrpg", "local_protagonist", "low_fantasy", "magic", "magical_girl", "magitech", "gay_romance", "male_lead", "martial_arts", "mecha", "modern_knowledge", "monster_evolution", "multiple_lead", "harem", "mythos", "non-human_lead", "nonhumanoid_lead", "otome", "summoned_hero", "post_apocalyptic", "progression", "reader_interactive", "reincarnation", "romance", "ruling_class", "school_life", "secret_identity", "slice_of_life", "soft_sci-fi", "space_opera", "sports", "steampunk", "strategy", "strong_lead", "super_heroes", "supernatural", "survival", "system_invasion", "technologically_engineered", "loop", "time_travel", "tower", "urban_fantasy", "villainous_lead", "virtual_reality", "war_and_military", "wuxia" ], "enumTitles": [ "Anti-Hero Lead", "Anti-Villain Lead", "Apocalypse", "Artificial Intelligence", "Attractive Lead", "Chivalry", "Competing Love Interest", "Cozy", "Crafting", "Cultivation", "Cyberpunk", "Deck Building", "Dungeon Core", "Dungeon Crawler", "Dystopia", "Female Lead", "First Contact", "GameLit", "Gender Bender", "Genetically Engineered", "Grimdark", "Hard Sci-fi", "High Fantasy", "Kingdom Building", "Lesbian Romance", "LitRPG", "Local Protagonist", "Low Fantasy", "Magic", "Magical Girl", "Magitech", "Male Gay Romance", "Male Lead", "Martial Arts", "Mecha", "Modern Knowledge", "Monster Evolution", "Multiple Lead Characters", "Multiple Lovers", "Mythos", "Non-Human Lead", "Non-Humanoid Lead", "Otome", "Portal Fantasy / Isekai", "Post Apocalyptic", "Progression", "Reader Interactive", "Reincarnation", "Romance Subplot", "Ruling Class", "School Life", "Secret Identity", "Slice of Life", "Soft Sci-fi", "Space Opera", "Sports", "Steampunk", "Strategy", "Strong Lead", "Super Heroes", "Supernatural", "Survival", "System Invasion", "Technologically Engineered", "Time Loop", "Time Travel", "Tower", "Urban Fantasy", "Villainous Lead", "Virtual Reality", "War and Military", "Wuxia" ] }, "default": [] }, "contentWarnings": { "title": "Content warnings (mode=search)", "type": "array", "description": "Only include fictions flagged with at least one of these content warnings.", "items": { "type": "string", "enum": [ "ai_assisted", "ai_generated", "graphic_violence", "profanity", "sensitive", "sexuality" ], "enumTitles": [ "AI-Assisted Content", "AI-Generated Content", "Graphic Violence", "Profanity", "Sensitive Content", "Sexual Content" ] }, "default": [] }, "excludeTags": { "title": "Exclude genres/tags/warnings (mode=search)", "type": "array", "description": "Exclude fictions tagged with any of these genres, tags, or content warnings.", "items": { "type": "string", "enum": [ "action", "adventure", "comedy", "contemporary", "drama", "fantasy", "historical", "horror", "mystery", "psychological", "romance_main", "satire", "sci_fi", "one_shot", "thriller", "tragedy", "anti-hero_lead", "antivillain_lead", "apocalypse", "artificial_intelligence", "attractive_lead", "chivalry", "competing_love", "cozy", "crafting", "cultivation", "cyberpunk", "deck_building", "dungeon_core", "dungeon_crawler", "dystopia", "female_lead", "first_contact", "gamelit", "gender_bender", "genetically_engineered", "grimdark", "hard_sci-fi", "high_fantasy", "kingdom_building", "lesbian_romance", "litrpg", "local_protagonist", "low_fantasy", "magic", "magical_girl", "magitech", "gay_romance", "male_lead", "martial_arts", "mecha", "modern_knowledge", "monster_evolution", "multiple_lead", "harem", "mythos", "non-human_lead", "nonhumanoid_lead", "otome", "summoned_hero", "post_apocalyptic", "progression", "reader_interactive", "reincarnation", "romance", "ruling_class", "school_life", "secret_identity", "slice_of_life", "soft_sci-fi", "space_opera", "sports", "steampunk", "strategy", "strong_lead", "super_heroes", "supernatural", "survival", "system_invasion", "technologically_engineered", "loop", "time_travel", "tower", "urban_fantasy", "villainous_lead", "virtual_reality", "war_and_military", "wuxia", "ai_assisted", "ai_generated", "graphic_violence", "profanity", "sensitive", "sexuality" ], "enumTitles": [ "Action", "Adventure", "Comedy", "Contemporary", "Drama", "Fantasy", "Historical", "Horror", "Mystery", "Psychological", "Romance", "Satire", "Sci-fi", "Short Story", "Thriller", "Tragedy", "Anti-Hero Lead", "Anti-Villain Lead", "Apocalypse", "Artificial Intelligence", "Attractive Lead", "Chivalry", "Competing Love Interest", "Cozy", "Crafting", "Cultivation", "Cyberpunk", "Deck Building", "Dungeon Core", "Dungeon Crawler", "Dystopia", "Female Lead", "First Contact", "GameLit", "Gender Bender", "Genetically Engineered", "Grimdark", "Hard Sci-fi", "High Fantasy", "Kingdom Building", "Lesbian Romance", "LitRPG", "Local Protagonist", "Low Fantasy", "Magic", "Magical Girl", "Magitech", "Male Gay Romance", "Male Lead", "Martial Arts", "Mecha", "Modern Knowledge", "Monster Evolution", "Multiple Lead Characters", "Multiple Lovers", "Mythos", "Non-Human Lead", "Non-Humanoid Lead", "Otome", "Portal Fantasy / Isekai", "Post Apocalyptic", "Progression", "Reader Interactive", "Reincarnation", "Romance Subplot", "Ruling Class", "School Life", "Secret Identity", "Slice of Life", "Soft Sci-fi", "Space Opera", "Sports", "Steampunk", "Strategy", "Strong Lead", "Super Heroes", "Supernatural", "Survival", "System Invasion", "Technologically Engineered", "Time Loop", "Time Travel", "Tower", "Urban Fantasy", "Villainous Lead", "Virtual Reality", "War and Military", "Wuxia", "AI-Assisted Content", "AI-Generated Content", "Graphic Violence", "Profanity", "Sensitive Content", "Sexual Content" ] }, "default": [] }, "status": { "title": "Status (mode=search)", "type": "array", "description": "Only include fictions with one of these statuses. Leave empty for all statuses.", "items": { "type": "string", "enum": [ "COMPLETED", "DROPPED", "ONGOING", "HIATUS", "INACTIVE", "STUB" ], "enumTitles": [ "Completed", "Dropped", "Ongoing", "Hiatus", "Inactive", "Stub" ] }, "default": [] }, "fictionType": { "title": "Fiction type (mode=search)", "enum": [ "ALL", "fanfiction", "original" ], "type": "string", "description": "Filter by original work vs fan fiction.", "default": "ALL" }, "minPages": { "title": "Min pages (mode=search)", "minimum": 0, "maximum": 20000, "type": "integer", "description": "Minimum estimated printed-book page count (275 words/page)." }, "maxPages": { "title": "Max pages (mode=search)", "minimum": 0, "maximum": 20000, "type": "integer", "description": "Maximum estimated printed-book page count (275 words/page)." }, "minRating": { "title": "Min rating (mode=search)", "minimum": 0, "maximum": 5, "type": "number", "description": "Minimum overall rating, 0-5." }, "maxRating": { "title": "Max rating (mode=search)", "minimum": 0, "maximum": 5, "type": "number", "description": "Maximum overall rating, 0-5." }, "orderBy": { "title": "Order by (mode=search)", "enum": [ "relevance", "popularity", "rating", "last_update", "release_date", "followers", "length", "views", "title", "author" ], "type": "string", "description": "Sort order for search results.", "default": "relevance" }, "sortDirection": { "title": "Sort direction (mode=search)", "enum": [ "asc", "desc" ], "type": "string", "description": "Ascending or descending sort order.", "default": "desc" }, "fictionUrls": { "title": "Fiction URLs or IDs (mode=fictionDetail)", "type": "array", "description": "Royal Road fiction URLs (e.g. https://www.royalroad.com/fiction/21220/mother-of-learning) or bare numeric fiction IDs.", "default": [], "items": { "type": "string" } }, "authorUrls": { "title": "Author profile URLs or IDs (mode=byAuthor)", "type": "array", "description": "Royal Road author profile URLs (e.g. https://www.royalroad.com/profile/100374) or bare numeric profile IDs.", "default": [], "items": { "type": "string" } }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hard cap on emitted records.", "default": 25 }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Optional. Royal Road works from Apify datacenter IPs without any proxy at all. Leave disabled (default) to avoid proxy usage entirely; only enable if you start seeing 403/429 errors from Royal Road.", "default": { "useApifyProxy": false } } } }, "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 } } } } } } } } } } ```