Archive of Our Own (AO3) Scraper

Scrape Archive of Our Own (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

{
  "mode": "search",
  "searchQuery": "time travel",
  "rating": ["10", "11"],
  "completeStatus": "complete",
  "wordCountMin": 5000,
  "sortBy": "kudos_count",
  "sortDirection": "desc",
  "maxItems": 50
}

Example: browse a fandom

{
  "mode": "byFandom",
  "fandomTag": "Harry Potter - J. K. Rowling",
  "category": ["23"],
  "singleChapterOnly": true,
  "maxItems": 30
}

Example: an author's works

{
  "mode": "byAuthor",
  "username": "owlwww",
  "maxItems": 50
}

Example: fetch specific works with chapter text

{
  "mode": "byUrls",
  "workUrls": ["https://archiveofourown.org/works/33190462"],
  "includeChapterText": true,
  "chapterNumber": 1
}

Example: browse a gift-exchange collection, sorted by kudos

{
  "mode": "byCollection",
  "collectionName": "yuletide2023",
  "sortBy": "kudos_count",
  "maxItems": 50
}

Example: fetch a series and all its works

{
  "mode": "bySeries",
  "seriesId": "https://archiveofourown.org/series/5000",
  "maxItems": 50
}

Example: find the exact canonical tag name before using it as a filter

{
  "mode": "tagSearch",
  "tagSearchQuery": "hurt comfort",
  "tagSearchType": "Freeform",
  "tagSearchCanonicalOnly": true,
  "maxItems": 20
}

Example: find an author's exact username

{
  "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.