# Archive of Our Own (AO3) Scraper (`crawlerbros/archive-of-our-own-scraper`) Actor Scrape Archive of Our Own (AO3) - the largest fanfiction archive on the web. Search by keyword, browse by fandom or tag, list an author's works, or fetch full metadata for specific works. No login required. - **URL**: https://apify.com/crawlerbros/archive-of-our-own-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Developer tools, Integrations - **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 ## Archive of Our Own (AO3) Scraper Scrape [Archive of Our Own](https://archiveofourown.org) (AO3) — the largest fanfiction archive on the web, hosting tens of millions of works across every fandom imaginable. Search by keyword with full advanced-search facets, browse by fandom or tag, list an author's works, or fetch complete metadata for specific works by URL. No login, no cookies, no API key required. ### What this actor does - **Nine modes:** `search`, `byFandom`, `byTag`, `byAuthor`, `byUrls`, `byCollection`, `bySeries`, `tagSearch`, `authorSearch` - **Full advanced-search facets:** rating, archive warnings, category (pairing type), language, word count range, hits/kudos/comments/bookmarks range, completion status, crossover status, single-chapter (one-shot) filter, date-updated range, and 10 sort orders - **Refine any listing mode** (including `byCollection`) with title / creator / fandom / relationship / character / freeform-tag text filters - **Direct work lookup** by URL or numeric ID, with optional chapter-text (and per-chapter notes) extraction - **Browse a collection** (gift exchanges, challenges, fests) with the same full facet/sort support as search - **Fetch a series**: one series-summary record (creator, word/works totals, completion) plus every work in it - **Discover exact tag names** with `tagSearch` (autocomplete-style, returns tag type + use count) — solves the #1 cause of "0 results" from a mistyped fandom/tag name - **Discover exact usernames** with `authorSearch` before using `byAuthor` - **Restricted or removed works are reported**, never silently dropped or faked - **Empty fields are omitted** from every record ### Output per work - `workId`, `sourceUrl` - `title`, `authors[]`, `authorUrls[]` - `fandoms[]`, `relationships[]`, `characters[]`, `freeformTags[]` - `rating`, `warnings[]`, `category[]` - `language`, `summary` - `wordCount`, `chapterCount`, `chapterCountTotal`, `isComplete` - `comments`, `kudos`, `bookmarks`, `hits` - `seriesTitle`, `seriesUrl`, `seriesPart` - `collections[]`, `authorNotes`, `giftFor[]` (mode=byUrls) - `lastUpdated` (listing modes) or `publishedDate` / `updatedDate` (mode=byUrls) - `chapterTitles[]`, `chapterText`, `chapterTextChapterNumber`/`chapterTextScope` (mode=byUrls, opt-in only) - `chapterNotes`, `chapterEndNotes` (mode=byUrls, single-chapter opt-in scope, multi-chapter works only) - `recordType: "work"`, `scrapedAt` Restricted or unreachable works (mode=byUrls) are returned as `recordType: "error"` records with `workId`, `sourceUrl`, and an `error` message instead of fabricated data. ### Output per series (mode=bySeries) - `seriesId`, `sourceUrl`, `seriesTitle` - `creators[]`, `creatorUrls[]` - `beginDate`, `updatedDate`, `description` - `wordCount`, `worksCount`, `isComplete`, `bookmarks` - `recordType: "series"`, `scrapedAt` Followed by one `recordType: "work"` record (same shape as listing modes) per work in the series. ### Output per tag (mode=tagSearch) - `tagName`, `sourceUrl`, `tagType` (Fandom / Character / Relationship / Freeform / UnsortedTag / etc.), `useCount` - `recordType: "tag"`, `scrapedAt` ### Output per author (mode=authorSearch) - `username`, `pseud`, `displayName`, `profileUrl` - `worksCount`, `worksUrl`, `bookmarksCount`, `bookmarksUrl`, `iconUrl` (when a real, non-default avatar is set) - `recordType: "author"`, `scrapedAt` ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | `search` | `search` / `byFandom` / `byTag` / `byAuthor` / `byUrls` / `byCollection` / `bySeries` / `tagSearch` / `authorSearch` | | `searchQuery` | string | `time travel` | Free-text query (mode=search); also refines other listing modes | | `titleQuery` | string | – | Restrict to works whose title contains this text | | `creators` | string | – | Restrict to a creator name | | `fandomNames` | string | – | Comma-separated fandom names to refine results | | `relationshipNames` | string | – | Comma-separated relationship tags to refine results | | `characterNames` | string | – | Comma-separated character tags to refine results | | `freeformTags` | string | – | Comma-separated additional tags to refine results | | `fandomTag` | string | – | Exact fandom tag (mode=byFandom) | | `tagName` | string | – | Exact relationship/character/freeform tag (mode=byTag) | | `username` | string | – | AO3 username (mode=byAuthor) | | `pseud` | string | – | Restrict to one pseud of the username (mode=byAuthor) | | `collectionName` | string | – | AO3 collection slug (mode=byCollection), e.g. `yuletide2023` | | `seriesId` | string | – | Series URL or numeric ID (mode=bySeries) | | `tagSearchQuery` | string | – | Tag name contains this text (mode=tagSearch) | | `tagSearchType` | string | any | Restrict to `Fandom` / `Character` / `Relationship` / `Freeform` (mode=tagSearch) | | `tagSearchCanonicalOnly` | bool | `false` | Only canonical (wrangled) tags (mode=tagSearch) | | `authorSearchQuery` | string | – | Username/pseud search text (mode=authorSearch) | | `authorSearchFandom` | string | – | Restrict author search to a fandom (mode=authorSearch) | | `workUrls` | array | – | Work URLs or numeric IDs (mode=byUrls) | | `includeChapterText` | bool | `false` | Include one chapter's full text (mode=byUrls) | | `chapterNumber` | int | `1` | Which chapter's text to include (mode=byUrls) | | `allChaptersText` | bool | `false` | Include every chapter's text, capped ~300k chars (mode=byUrls) | | `rating` | array | – | Content ratings to include (multi-select) | | `warnings` | array | – | Archive warnings to include (multi-select) | | `category` | array | – | Relationship categories to include (multi-select) | | `language` | string | any | Work language | | `wordCountMin` / `wordCountMax` | int | – | Word count bounds | | `hitsMin` / `hitsMax` | int | – | Hits (views) bounds | | `kudosMin` / `kudosMax` | int | – | Kudos count bounds | | `commentsMin` / `commentsMax` | int | – | Comment count bounds | | `bookmarksMin` / `bookmarksMax` | int | – | Bookmark count bounds | | `completeStatus` | string | `any` | `any` / `complete` / `wip` | | `crossoverStatus` | string | `any` | `any` / `yes` / `no` | | `singleChapterOnly` | bool | `false` | One-shots only | | `dateUpdatedFrom` / `dateUpdatedTo` | string | – | Date-updated range, e.g. `01 January 2024` | | `sortBy` | string | `_score` | Sort field (best match, date, word count, hits, kudos, comments, bookmarks, title, creator) | | `sortDirection` | string | `desc` | `asc` / `desc` | | `maxItems` | int | `20` | Hard cap on emitted records (1–2000) | `hitsMin/Max`, `kudosMin/Max`, `commentsMin/Max`, `bookmarksMin/Max`, and all the facet filters above them apply to `search`, `byFandom`, `byTag`, `byAuthor`, and `byCollection` (every listing mode that goes through AO3's `work_search` engine). #### Example: search with facets ```json { "mode": "search", "searchQuery": "time travel", "rating": ["10", "11"], "completeStatus": "complete", "wordCountMin": 5000, "sortBy": "kudos_count", "sortDirection": "desc", "maxItems": 50 } ```` #### Example: browse a fandom ```json { "mode": "byFandom", "fandomTag": "Harry Potter - J. K. Rowling", "category": ["23"], "singleChapterOnly": true, "maxItems": 30 } ``` #### Example: an author's works ```json { "mode": "byAuthor", "username": "owlwww", "maxItems": 50 } ``` #### Example: fetch specific works with chapter text ```json { "mode": "byUrls", "workUrls": ["https://archiveofourown.org/works/33190462"], "includeChapterText": true, "chapterNumber": 1 } ``` #### Example: browse a gift-exchange collection, sorted by kudos ```json { "mode": "byCollection", "collectionName": "yuletide2023", "sortBy": "kudos_count", "maxItems": 50 } ``` #### Example: fetch a series and all its works ```json { "mode": "bySeries", "seriesId": "https://archiveofourown.org/series/5000", "maxItems": 50 } ``` #### Example: find the exact canonical tag name before using it as a filter ```json { "mode": "tagSearch", "tagSearchQuery": "hurt comfort", "tagSearchType": "Freeform", "tagSearchCanonicalOnly": true, "maxItems": 20 } ``` #### Example: find an author's exact username ```json { "mode": "authorSearch", "authorSearchQuery": "owlwww", "maxItems": 10 } ``` ### Use cases - **Fandom research** — track how a fandom's output, pairings, and tag trends evolve over time - **Recommendation engines** — build a fic recommender from tags, ratings, and kudos/hits ratios - **Content moderation tooling** — audit works by rating/warning combination - **Academic study of fan culture** — bulk-export tag taxonomies and metadata for transformative-works research - **Author portfolio tracking** — monitor an author's published works and stats over time - **Archival/backup** — capture metadata (and optionally chapter text) for works you want to preserve ### FAQ **Do I need an AO3 account or cookies?** No. Search, fandom/tag browsing, author listings, and public work pages all work without login. **Why are some works returned as `recordType: "error"`?** A small number of AO3 works are restricted to registered/logged-in users, or have been deleted. Rather than fabricate data, the actor reports these as typed error records with the reason. **Does the actor scrape full chapter text by default?** No. Work-level metadata (tags, stats, summary) is the default deliverable. Set `includeChapterText` or `allChaptersText` on `mode=byUrls` to opt into chapter text. **How is `category` different from `relationships`?** `category` is AO3's broad pairing-type facet (Gen, F/M, M/M, F/F, Multi, Other). `relationships` lists the specific pairing tags (e.g. `Harry Potter/Draco Malfoy`). **What does `isComplete` mean for a work with unknown total chapters?** AO3 shows `chapterCount/?` for works where the author hasn't committed to a final chapter count. These are treated as incomplete (`isComplete: false`) until the author marks the work complete. **Is there a rate limit?** AO3 is a volunteer-run nonprofit archive — the actor uses modest, jittered delays between requests and automatically retries on rate-limit or server-error responses. **Can I combine fandom/tag browsing with search facets?** Yes — `rating`, `warnings`, `category`, `language`, word count, hits/kudos/comments/bookmarks, completion, crossover, single-chapter, and date filters all apply on `byFandom`, `byTag`, `byAuthor`, and `byCollection` in addition to `search`. **Why do I keep getting 0 results from `fandomTag`/`tagName`/`fandomNames`?** AO3 tag filters require the *exact* canonical tag spelling. Use `mode=tagSearch` first to look up the exact tag name (and its type/use count) before using it as a filter — this is the single most common cause of empty results. **What's the difference between `byTag`/`byFandom` and `tagSearch`?** `byTag`/`byFandom` fetch the *works* tagged with an exact tag you already know. `tagSearch` is a lookup/autocomplete tool that helps you *find* the exact tag name (and confirms whether it's a Fandom, Character, Relationship, or Freeform tag) — it returns tag metadata, not works. **What does `mode=bySeries` return?** One `recordType: "series"` summary record (title, creator, word/works totals, completion, bookmarks) followed by every work in the series as normal `recordType: "work"` records — series part numbers are included on each work. **Are `chapterNotes`/`chapterEndNotes` always present?** No — only when `includeChapterText` is on, the work has multiple chapters, and the author actually wrote notes for that chapter. AO3 also shows a generic "(See the end of the chapter for notes.)" cross-reference on some chapters; the actor filters that boilerplate out rather than reporting it as real note content. # Actor input Schema ## `mode` (type: `string`): What to fetch. ## `searchQuery` (type: `string`): Free-text query searched across title, summary, tags and body. Required for mode=search. Also usable as an optional refine filter on byFandom/byTag/byAuthor — leave blank there to avoid narrowing results. ## `titleQuery` (type: `string`): Restrict to works whose title contains this text. ## `creators` (type: `string`): Restrict to works by this creator (pseud or username). ## `fandomNames` (type: `string`): Comma-separated fandom names to refine results, e.g. `Harry Potter - J. K. Rowling, Marvel Cinematic Universe`. ## `relationshipNames` (type: `string`): Comma-separated relationship tags to refine results, e.g. `Harry Potter/Draco Malfoy`. ## `characterNames` (type: `string`): Comma-separated character tags to refine results. ## `freeformTags` (type: `string`): Comma-separated additional/freeform tags to refine results, e.g. `Fluff, Slow Burn`. ## `fandomTag` (type: `string`): Exact AO3 fandom tag to browse, e.g. `Harry Potter - J. K. Rowling`, `Marvel Cinematic Universe`, `Naruto`. ## `tagName` (type: `string`): Exact AO3 tag to browse — a relationship, character, or freeform tag, e.g. `Fluff`, `Hurt/Comfort`. ## `username` (type: `string`): AO3 username whose public works to list. ## `pseud` (type: `string`): Restrict to a specific pseudonym of the username above. Leave blank to include all of the user's pseuds. ## `collectionName` (type: `string`): AO3 collection slug to browse, e.g. `yuletide2023` (from `archiveofourown.org/collections/yuletide2023`). ## `seriesId` (type: `string`): AO3 series URL (e.g. `https://archiveofourown.org/series/5000`) or bare numeric series ID. Emits one series-summary record plus every work in the series. ## `tagSearchQuery` (type: `string`): Find AO3 tags whose name contains this text — useful for discovering the exact canonical tag name/spelling before using it in `fandomTag`, `tagName`, or the refine filters. ## `tagSearchType` (type: `string`): Restrict tag search results to one tag category. ## `tagSearchCanonicalOnly` (type: `boolean`): Only return AO3's canonical (wrangled) tags, excluding synonyms/non-canonical variants. ## `authorSearchQuery` (type: `string`): Find AO3 users/pseuds matching this text — useful for discovering the exact username/pseud spelling before using it in `username` (mode=byAuthor). ## `authorSearchFandom` (type: `string`): Restrict author search results to users active in this fandom. ## `workUrls` (type: `array`): AO3 work URLs (e.g. `https://archiveofourown.org/works/12345678`) or bare numeric work IDs. ## `includeChapterText` (type: `boolean`): Fetch and include the full text of one chapter (see Chapter number below). Off by default — work-level metadata is the primary deliverable. ## `chapterNumber` (type: `integer`): Which chapter's text to include when 'Include chapter text' is on. 1 = first chapter. ## `allChaptersText` (type: `boolean`): Overrides Chapter number — fetches every chapter's text into one field (capped at ~300,000 characters per work). Use sparingly, this is a heavy operation. ## `rating` (type: `array`): Filter by a single content rating (AO3 gives each work exactly one rating, so its own site returns zero results if you select more than one at once — only the first selection is used). Leave empty for all ratings. ## `warnings` (type: `array`): Filter by one or more archive warnings. Leave empty for all. ## `category` (type: `array`): Filter by one or more relationship categories. Leave empty for all. ## `language` (type: `string`): Filter to a specific work language. Leave as 'Any language' to include all. ## `wordCountMin` (type: `integer`): Only include works with at least this many words. ## `wordCountMax` (type: `integer`): Only include works with at most this many words. ## `hitsMin` (type: `integer`): Only include works with at least this many hits (views). ## `hitsMax` (type: `integer`): Only include works with at most this many hits (views). ## `kudosMin` (type: `integer`): Only include works with at least this many kudos. ## `kudosMax` (type: `integer`): Only include works with at most this many kudos. ## `commentsMin` (type: `integer`): Only include works with at least this many comments. ## `commentsMax` (type: `integer`): Only include works with at most this many comments. ## `bookmarksMin` (type: `integer`): Only include works with at least this many bookmarks. ## `bookmarksMax` (type: `integer`): Only include works with at most this many bookmarks. ## `completeStatus` (type: `string`): Filter by whether the work is finished. ## `crossoverStatus` (type: `string`): Filter by whether the work crosses over multiple fandoms. ## `singleChapterOnly` (type: `boolean`): Only include one-shots (works with exactly one posted chapter). ## `dateUpdatedFrom` (type: `string`): Only include works last updated after this date, e.g. `01 January 2024`. ## `dateUpdatedTo` (type: `string`): Only include works last updated before this date, e.g. `31 December 2024`. ## `sortBy` (type: `string`): Result ordering for listing modes. ## `sortDirection` (type: `string`): Ascending or descending order for the chosen sort field. ## `maxItems` (type: `integer`): Hard cap on emitted records. ## Actor input object example ```json { "mode": "search", "searchQuery": "time travel", "fandomTag": "Harry Potter - J. K. Rowling", "tagName": "Fluff", "collectionName": "yuletide2023", "tagSearchQuery": "fluff", "tagSearchType": "", "tagSearchCanonicalOnly": false, "workUrls": [], "includeChapterText": false, "chapterNumber": 1, "allChaptersText": false, "rating": [], "warnings": [], "category": [], "language": "", "completeStatus": "any", "crossoverStatus": "any", "singleChapterOnly": false, "sortBy": "_score", "sortDirection": "desc", "maxItems": 20 } ``` # Actor output Schema ## `works` (type: `string`): Dataset containing all scraped AO3 records (works, and — depending on mode — series summaries, tag-search results, or author-search results). # 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": "search", "searchQuery": "time travel", "fandomTag": "Harry Potter - J. K. Rowling", "tagName": "Fluff", "collectionName": "yuletide2023", "tagSearchQuery": "fluff", "tagSearchType": "", "tagSearchCanonicalOnly": false, "workUrls": [], "includeChapterText": false, "chapterNumber": 1, "allChaptersText": false, "rating": [], "warnings": [], "category": [], "language": "", "completeStatus": "any", "crossoverStatus": "any", "singleChapterOnly": false, "sortBy": "_score", "sortDirection": "desc", "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/archive-of-our-own-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": "search", "searchQuery": "time travel", "fandomTag": "Harry Potter - J. K. Rowling", "tagName": "Fluff", "collectionName": "yuletide2023", "tagSearchQuery": "fluff", "tagSearchType": "", "tagSearchCanonicalOnly": False, "workUrls": [], "includeChapterText": False, "chapterNumber": 1, "allChaptersText": False, "rating": [], "warnings": [], "category": [], "language": "", "completeStatus": "any", "crossoverStatus": "any", "singleChapterOnly": False, "sortBy": "_score", "sortDirection": "desc", "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/archive-of-our-own-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": "search", "searchQuery": "time travel", "fandomTag": "Harry Potter - J. K. Rowling", "tagName": "Fluff", "collectionName": "yuletide2023", "tagSearchQuery": "fluff", "tagSearchType": "", "tagSearchCanonicalOnly": false, "workUrls": [], "includeChapterText": false, "chapterNumber": 1, "allChaptersText": false, "rating": [], "warnings": [], "category": [], "language": "", "completeStatus": "any", "crossoverStatus": "any", "singleChapterOnly": false, "sortBy": "_score", "sortDirection": "desc", "maxItems": 20 }' | apify call crawlerbros/archive-of-our-own-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/archive-of-our-own-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Archive of Our Own (AO3) Scraper", "description": "Scrape Archive of Our Own (AO3) - the largest fanfiction archive on the web. Search by keyword, browse by fandom or tag, list an author's works, or fetch full metadata for specific works. No login required.", "version": "1.0", "x-build-id": "mG8J0VvzjBo5msoQe" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~archive-of-our-own-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-archive-of-our-own-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~archive-of-our-own-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-archive-of-our-own-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~archive-of-our-own-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-archive-of-our-own-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": [ "search", "byFandom", "byTag", "byAuthor", "byUrls", "byCollection", "bySeries", "tagSearch", "authorSearch" ], "type": "string", "description": "What to fetch.", "default": "search" }, "searchQuery": { "title": "Search query (mode=search)", "type": "string", "description": "Free-text query searched across title, summary, tags and body. Required for mode=search. Also usable as an optional refine filter on byFandom/byTag/byAuthor — leave blank there to avoid narrowing results.", "default": "" }, "titleQuery": { "title": "Title contains", "type": "string", "description": "Restrict to works whose title contains this text." }, "creators": { "title": "Creator / author name", "type": "string", "description": "Restrict to works by this creator (pseud or username)." }, "fandomNames": { "title": "Fandom names", "type": "string", "description": "Comma-separated fandom names to refine results, e.g. `Harry Potter - J. K. Rowling, Marvel Cinematic Universe`." }, "relationshipNames": { "title": "Relationship tags", "type": "string", "description": "Comma-separated relationship tags to refine results, e.g. `Harry Potter/Draco Malfoy`." }, "characterNames": { "title": "Character tags", "type": "string", "description": "Comma-separated character tags to refine results." }, "freeformTags": { "title": "Additional (freeform) tags", "type": "string", "description": "Comma-separated additional/freeform tags to refine results, e.g. `Fluff, Slow Burn`." }, "fandomTag": { "title": "Fandom (mode=byFandom)", "type": "string", "description": "Exact AO3 fandom tag to browse, e.g. `Harry Potter - J. K. Rowling`, `Marvel Cinematic Universe`, `Naruto`." }, "tagName": { "title": "Tag (mode=byTag)", "type": "string", "description": "Exact AO3 tag to browse — a relationship, character, or freeform tag, e.g. `Fluff`, `Hurt/Comfort`." }, "username": { "title": "Username (mode=byAuthor)", "type": "string", "description": "AO3 username whose public works to list." }, "pseud": { "title": "Pseud (mode=byAuthor, optional)", "type": "string", "description": "Restrict to a specific pseudonym of the username above. Leave blank to include all of the user's pseuds." }, "collectionName": { "title": "Collection name (mode=byCollection)", "type": "string", "description": "AO3 collection slug to browse, e.g. `yuletide2023` (from `archiveofourown.org/collections/yuletide2023`)." }, "seriesId": { "title": "Series URL or ID (mode=bySeries)", "type": "string", "description": "AO3 series URL (e.g. `https://archiveofourown.org/series/5000`) or bare numeric series ID. Emits one series-summary record plus every work in the series." }, "tagSearchQuery": { "title": "Tag name contains (mode=tagSearch)", "type": "string", "description": "Find AO3 tags whose name contains this text — useful for discovering the exact canonical tag name/spelling before using it in `fandomTag`, `tagName`, or the refine filters." }, "tagSearchType": { "title": "Tag type (mode=tagSearch, optional)", "enum": [ "", "Fandom", "Character", "Relationship", "Freeform" ], "type": "string", "description": "Restrict tag search results to one tag category.", "default": "" }, "tagSearchCanonicalOnly": { "title": "Canonical tags only (mode=tagSearch)", "type": "boolean", "description": "Only return AO3's canonical (wrangled) tags, excluding synonyms/non-canonical variants.", "default": false }, "authorSearchQuery": { "title": "Search all fields (mode=authorSearch)", "type": "string", "description": "Find AO3 users/pseuds matching this text — useful for discovering the exact username/pseud spelling before using it in `username` (mode=byAuthor)." }, "authorSearchFandom": { "title": "Fandom filter (mode=authorSearch, optional)", "type": "string", "description": "Restrict author search results to users active in this fandom." }, "workUrls": { "title": "Work URLs or IDs (mode=byUrls)", "type": "array", "description": "AO3 work URLs (e.g. `https://archiveofourown.org/works/12345678`) or bare numeric work IDs.", "default": [], "items": { "type": "string" } }, "includeChapterText": { "title": "Include chapter text (mode=byUrls)", "type": "boolean", "description": "Fetch and include the full text of one chapter (see Chapter number below). Off by default — work-level metadata is the primary deliverable.", "default": false }, "chapterNumber": { "title": "Chapter number (mode=byUrls)", "minimum": 1, "maximum": 500, "type": "integer", "description": "Which chapter's text to include when 'Include chapter text' is on. 1 = first chapter.", "default": 1 }, "allChaptersText": { "title": "Include ALL chapters' text (mode=byUrls)", "type": "boolean", "description": "Overrides Chapter number — fetches every chapter's text into one field (capped at ~300,000 characters per work). Use sparingly, this is a heavy operation.", "default": false }, "rating": { "title": "Rating", "maxItems": 1, "type": "array", "description": "Filter by a single content rating (AO3 gives each work exactly one rating, so its own site returns zero results if you select more than one at once — only the first selection is used). Leave empty for all ratings.", "items": { "type": "string", "enum": [ "9", "10", "11", "12", "13" ], "enumTitles": [ "Not Rated", "General Audiences", "Teen And Up Audiences", "Mature", "Explicit" ] }, "default": [] }, "warnings": { "title": "Archive warnings", "type": "array", "description": "Filter by one or more archive warnings. Leave empty for all.", "items": { "type": "string", "enum": [ "14", "16", "17", "18", "19", "20" ], "enumTitles": [ "Creator Chose Not To Use Archive Warnings", "No Archive Warnings Apply", "Graphic Depictions Of Violence", "Major Character Death", "Rape/Non-Con", "Underage Sex" ] }, "default": [] }, "category": { "title": "Category", "type": "array", "description": "Filter by one or more relationship categories. Leave empty for all.", "items": { "type": "string", "enum": [ "21", "22", "23", "116", "2246", "24" ], "enumTitles": [ "Gen", "F/M", "M/M", "F/F", "Multi", "Other" ] }, "default": [] }, "language": { "title": "Language", "enum": [ "", "en", "es", "fr", "de", "it", "pt", "pt-BR", "ru", "ja", "zh", "ko", "ar", "pl", "nl", "sv", "fi", "no", "da", "tr", "cs", "el", "he", "hi", "id", "th", "vi", "uk", "ro", "hu", "bg", "hr", "sr", "sk", "lt", "lv", "et", "ca", "eu", "gl", "af", "ms" ], "type": "string", "description": "Filter to a specific work language. Leave as 'Any language' to include all.", "default": "" }, "wordCountMin": { "title": "Word count (min)", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Only include works with at least this many words." }, "wordCountMax": { "title": "Word count (max)", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Only include works with at most this many words." }, "hitsMin": { "title": "Hits (min)", "minimum": 0, "maximum": 100000000, "type": "integer", "description": "Only include works with at least this many hits (views)." }, "hitsMax": { "title": "Hits (max)", "minimum": 0, "maximum": 100000000, "type": "integer", "description": "Only include works with at most this many hits (views)." }, "kudosMin": { "title": "Kudos (min)", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Only include works with at least this many kudos." }, "kudosMax": { "title": "Kudos (max)", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Only include works with at most this many kudos." }, "commentsMin": { "title": "Comments (min)", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Only include works with at least this many comments." }, "commentsMax": { "title": "Comments (max)", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Only include works with at most this many comments." }, "bookmarksMin": { "title": "Bookmarks (min)", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Only include works with at least this many bookmarks." }, "bookmarksMax": { "title": "Bookmarks (max)", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Only include works with at most this many bookmarks." }, "completeStatus": { "title": "Completion status", "enum": [ "any", "complete", "wip" ], "type": "string", "description": "Filter by whether the work is finished.", "default": "any" }, "crossoverStatus": { "title": "Crossover status", "enum": [ "any", "yes", "no" ], "type": "string", "description": "Filter by whether the work crosses over multiple fandoms.", "default": "any" }, "singleChapterOnly": { "title": "Single-chapter works only", "type": "boolean", "description": "Only include one-shots (works with exactly one posted chapter).", "default": false }, "dateUpdatedFrom": { "title": "Updated after (mode=search/byFandom/byTag/byAuthor)", "type": "string", "description": "Only include works last updated after this date, e.g. `01 January 2024`." }, "dateUpdatedTo": { "title": "Updated before (mode=search/byFandom/byTag/byAuthor)", "type": "string", "description": "Only include works last updated before this date, e.g. `31 December 2024`." }, "sortBy": { "title": "Sort by", "enum": [ "_score", "created_at", "revised_at", "word_count", "hits", "kudos_count", "comments_count", "bookmarks_count", "title_to_sort_on", "authors_to_sort_on" ], "type": "string", "description": "Result ordering for listing modes.", "default": "_score" }, "sortDirection": { "title": "Sort direction", "enum": [ "asc", "desc" ], "type": "string", "description": "Ascending or descending order for the chosen sort field.", "default": "desc" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Hard cap on emitted records.", "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 } } } } } } } } } } ```