pyalex

PyAlex is a lightweight Python wrapper for the OpenAlex REST API, designed to stay close to the original service's design. It allows you to extract, aggregate, or search scholarly data including works, authors, and institutions.

Supported Entities

• Work
• Author
• Source
• Institution
• Concept
• Topic
• Publisher
• Funder

Key Capabilities

• Pipe operations: Chain multiple operations in a sequence for readable queries.
• Plaintext abstracts: Automatically converts OpenAlex's inverted index abstracts into plaintext.
• Semantic search: Find similar works using Works().similar().
• Content fetching: Retrieve full-text content in PDF or TEI XML formats.
• API features: Supports filtering, searching, grouping, field selection, sampling, pagination, and authentication.

As of February 13, 2026, an API key is required to use the OpenAlex API. Using a free API key increases your daily credit limit from 100 to 100,000.

To configure PyAlex, obtain a key from openalex.org and set it via pyalex.config.api_key.

import pyalex

pyalex.config.api_key = "<YOUR_API_KEY>"

PyAlex requires Python 3.8 or later. You can install it using pip:

pip install pyalex

By default, PyAlex raises an error on the first API failure. You can configure the pyalex.config object to handle transient errors by setting:

• max_retries: Number of retry attempts (set > 0 to enable).
• retry_backoff_factor: The delay factor between retries.
• retry_http_codes: A list of HTTP status codes that should trigger a retry (e.g., 429 for Rate Limiting, 500, 503).

from pyalex import config

config.max_retries = 0
config.retry_backoff_factor = 0.1
config.retry_http_codes = [429, 500, 503]

Use Works().filter(author={"id": "AUTHOR_ID"}).get() to retrieve publications for a specific author.

Note: By default, this only retrieves the first 25 works. To retrieve the full list, you must implement paging.

from pyalex import Works

Works().filter(author={"id": "A2887243803"}).get()

PyAlex supports complex filtering and grouping for data analysis:

• Filtering by properties: e.g., filter(institutions={"is_global_south": True}) or filter(type="dataset").
• Grouping: Use .group_by("field_name") to aggregate results.
• Sorting: Use .sort(field_name="desc" or "asc") to order results, such as by cited_by_count.

from pyalex import Works

# Dataset publications in the global south grouped by country code
Works() \
  .filter(institutions={"is_global_south":True}) \
  .filter(type="dataset") \
  .group_by("institutions.country_code") \
  .get()

# Most cited publications in an organisation using ROR ID
Works() \
  .filter(authorships={"institutions": {"ror": "04pp8hn57"}}) \
  .sort(cited_by_count="desc") \
  .get()

You can navigate citation networks using the Works class:

1. Outgoing Citations (Works referenced by a paper): Retrieve the list of IDs from the referenced_works field of a work object, then pass that list to Works().
2. Incoming Citations (Works that reference a paper): Use the .filter(cites="WORK_ID") method on the Works class.

from pyalex import Works

# Cited publications (works referenced by this paper)
w = Works()["W2741809807"]
Works()[w["referenced_works"]]

# Citing publications (other works that reference this paper)
Works().filter(cites="W2741809807").get()

To find an author within a specific institution, you must first search for the institution to retrieve its OpenAlex ID, then use that ID to filter your author search. The institution ID should be stripped of the https://openalex.org/ prefix when used in filters.

from pyalex import Authors, Institutions
import logging

# Search for the institution
insts = Institutions().search("MIT").get()
logging.info(f"{len(insts)} search results found for the institution")
inst_id = insts[0]["id"].replace("https://openalex.org/", "")

# Search for the author within the institution
auths = Authors().search("Daron Acemoglu").filter(affiliations={"institution":{"id": inst_id}}).get()
logging.info(f"{len(auths)} search results found for the author")
auth = auths[0]

Use the autocomplete function to suggest entity names. You can use the global autocomplete or call it on a specific entity class to restrict the type of entities returned.

from pyalex import autocomplete, Institutions, Works

# General autocomplete
autocomplete("stockholm resilience centre")

# Restricted to Institutions
Institutions().autocomplete("stockholm resilience centre")

# Autocomplete with filters
Works().filter(publication_year=2023).autocomplete("planetary boundaries")

For Work objects, you can access full-text content in PDF or TEI (Text Encoding Initiative) XML format if available.

Methods available:

• .get(): Returns the content.
• .download(filename): Saves the content to a file.
• .url: Returns the direct URL to the content.

from pyalex import Works

w = Works()["W4412002745"]

# Get content in memory
pdf_content = w.pdf.get()
tei_content = w.tei.get()

# Download to files
w.pdf.download("document.pdf")
w.tei.download("document.xml")

# Get URLs
pdf_url = w.pdf.url
tei_url = w.tei.url

To retrieve a random entity of a specific type, use the .random() method on the corresponding entity class.

from pyalex import Works, Authors, Sources, Institutions, Topics, Publishers, Funders

Works().random()
Authors().random()
Sources().random()
Institutions().random()
Topics().random()
Publishers().random()
Funders().random()

PyAlex supports two paging methods via the .paginate() method:

1. Cursor Paging (Default): Most efficient. Returns a pager object that can be iterated. Use per_page to set results per page (default 25). Use n_max=None to retrieve all results.
2. Basic (Offset) Paging: Use method="page" to use standard offset-based paging.

To iterate through all records easily, combine paginate() with itertools.chain.

from itertools import chain
from pyalex import Authors

# Cursor paging (default)
query = Authors().search_filter(display_name="einstein")
pager = query.paginate(per_page=200)

for page in pager:
    print(len(page))

# Efficiently iterate all records
for record in chain(*query.paginate(per_page=200)):
    print(record["id"])

# Basic paging
pager_basic = Authors().search_filter(display_name="einstein").paginate(method="page", per_page=200)