Skip to main content

An unofficial AO3 ( API

Project description


This is an unofficial API that let's you access some of AO3's ( data through Python.


Use the package manager pip to install AO3 API.

pip install ao3_api



There are 3 types of classes added by the API: AO3.Work, AO3.User and AO3.Session

You can use the AO3.Work class to pull data from a work stored in

>>> import AO3
>>> work = AO3.Work(14392692) # 14392692 is the workid
>>> work.title
'The Roots That Clutch'
>>> work.date_published, 4, 22)
>>> work.authors
>>> work.language

You can get the chapter text by calling work.load_chapters() followed by work.get_chapter_text(chapter)

>>> import AO3
>>> work = AO3.Work(14392692)
>>> work.load_chapters()
>>> text = work.get_chapter_text(1)
>>> print(' '.join(text.split(' ')[:20]))  # Print the first 20 words

Chapter Text
It all starts with a suggestion.Hey, we should make this a thing, Midoriya says one day, out of the

If you don't call work.load_chapters() you might get this error:

Traceback (most recent call last):
  File "<pyshell#9>", line 1, in <module>
  File "C:\Python36\lib\site-packages\AO3\", line 27, in get_chapter_text
    raise utils.UnloadedError("Work.load_chapters() must be called first")
AO3.utils.UnloadedError: Work.load_chapters() must be called first

You can use the AO3.User class to pull data from a user profile:

>>> import AO3
>>> user = AO3.User("laquearia")
>>> user.url
>>> print(
I have no idea what I'm doing, but I know I'm doing it very, very well.  (Artist, 23, in love with tea. Check out my shit.)NOTE: I am known for my angst. Read my things with caution and a box of tissues.
>>>  # Number of works published

Use user.get_work_list(page) to get all the works in a page from the user. If you're not sure how many pages there are, use user.npages

If you have an account, you can login with using AO3.session(username, password) and get a session to access that that's only accessible when you're logged in.

>>> import AO3
>>> sess = AO3.session("myusername", "mypassword")
>>> sess.get_n_bookmarks()
>>> sess.get_bookmarks(page=1)  # Get all bookmarks in a page in the format (id, 'work title', ['author1', 'author2'])
[(123456, 'Work Title', ['author1'])]
>>> sess.get_subscriptions(page=1) # Get all subscriptions in a page in the format (id, 'work title', ['author1', 'author2'])
[(123456, 'Work Title', ['author1'])]

If you provide a wrong username / password this error will be raised:

Traceback (most recent call last):
  File "<pyshell#11>", line 1, in <module>
    s = AO3.Session("as", "as")
  File "C:\Python36\lib\site-packages\AO3\", line 20, in __init__
    raise utils.LoginError("Invalid username or password")
AO3.utils.LoginError: Invalid username or password

AO3.utils.workid_from_url(url) is a functions that returns the workid given a work url:

>>> import AO3
>>> AO3.utils.workid_from_url("")
>>> AO3.utils.workid_from_url("")
>>> AO3.utils.workid_from_url("works/14392692/chapters/33236241")

Future functionalities

In the future, if no official API is released, I might add a search option and more session options (subscribe to works, kudos and comment).

Contact info

For information or bug reports please contact



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ao3-api, version 0.0.2
Filename, size & hash File type Python version Upload date
ao3-api-0.0.2.tar.gz (5.6 kB) View hashes Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page