Aletheca: Asynchronous Python client for the OpenAlex API

Samuel Mok -- s.mok@utwente.nl -- 2025-2026

Aletheca is an async Python client for the OpenAlex API, built on bibliofabric.

Docs: utsmok.github.io/aletheca -- PyPI: aletheca -- License: MIT

Features

• Async by design -- built on httpx + asyncio with proper connection pooling
• Typed throughout -- Pydantic v2 models for all entities, PEP 561 py.typed marker
• Cursor pagination -- efficient iteration over large result sets via cursor-based auto-pagination
• Filter serialization -- automatic conversion to OpenAlex filter=key:value syntax with Pydantic filter models
• Safe types -- SafeList and SafeStr for None-safe traversal of API responses
• Convenience queries -- high-level functions for common workflows (works_by_author, citing_works, etc.)

Installation

uv add aletheca

Or with pip: pip install aletheca. Requires Python >=3.12.

Quick Start

import asyncio
from aletheca import AlethecaSession

async def main():
    async with AlethecaSession() as session:
        # Get a work by OpenAlex ID
        work = await session.works.get("W1234567890")
        print(work.title)

        # Search works
        results = await session.works.search(search="machine learning", page_size=10)
        for work in results.results:
            print(f"{work.title} ({work.publication_year})")

        # Iterate all works by an author (cursor-based auto-pagination)
        async for work in session.works.iterate(
            filters={"authorships.author.id": "A1234567890"},
            page_size=100,
        ):
            print(work.title)

asyncio.run(main())

No authentication required -- the OpenAlex API works without it. For higher rate limits, see Authentication.

Examples

All examples in examples/ are dual-purpose -- run as scripts or as interactive marimo notebooks:

# As a script
uv run examples/simple_example.py

# As an interactive notebook
uv run marimo edit examples/simple_example.py

See examples/README.md for details on running examples as interactive marimo notebooks.

Authentication

Aletheca auto-detects the OpenAlex API key from environment variables or .env files (prefixed with ALETHECA_). No auth is the default if nothing is configured.

ALETHECA_OPENALEX_API_KEY=your_api_key

Or pass explicitly:

async with AlethecaSession(api_key="your_api_key") as session:
    ...

With an API key you get faster responses (dedicated pool). Without one, you use the polite pool (slower).

→ Full guide: Authentication

Basic Usage

Get a single entity

work = await session.works.get("W2741809801")
print(work.title, work.doi, work.publication_year)

Search

results = await session.works.search(search="machine learning", page_size=5)
for work in results.results:
    print(work.title)

Iterate all results

async for work in session.works.iterate(
    filters={"publication_year": 2024, "is_oa": True},
    page_size=100,
):
    print(work.title)
    break  # stop when you want

Convenience queries

citations = await session.queries.citing_works("W2741809801")
print(f"{len(citations)} citations")

→ Full guide: Usage Basics · Works · All Entities

Known OpenAlex API Issues

Full bug report with reproduction steps: OPENALEX_BUG_REPORT.md.

• OpenAPI spec is substantially incomplete -- 50+ fields returned by the live API are missing from the spec schemas across all entity types. Several spec fields don't exist in the live API.
• Wrong field names in spec -- content_url (spec) vs content_urls (live), grants_count (spec) vs awards_count (live)
• Undocumented fields -- institution_awarded on Awards is not documented anywhere; 15+ nested Award filters are missing from the docs filter table
• Awards endpoint missing from llms.txt -- the awards endpoint is not listed in the API quick reference
• per_page max is 100 -- 200 still works but is deprecated legacy behavior, slated for removal (OpenAlex docs, 2026-08); all examples here use 100
• Keyword IDs are slug paths, not short IDs -- live keyword records carry ids like https://openalex.org/keywords/photosynthesis, and the single-record route rejects that full-URL form (nested slashes → HTML 404) even though /works/https://openalex.org/W… is accepted. get() normalizes both forms.
• Awards 400 body is the authoritative filter list -- the awards endpoint rejects several filters its docs summaries suggest (funder.country_code, plain display_name, lead_investigator.id, from_/to_*_date) and its 400 error body enumerates all 40 valid filters, which is more complete than any docs table.

Development

uv sync --all-groups --all-extras         # install everything
uv run ruff check src/ --fix              # lint
uv run ruff format src/                   # format
uvx ty check src/                         # type check
uv run pytest tests/                      # run tests
uv run pytest --cov=aletheca tests/       # coverage (CI threshold: 95%)
uv build                                  # build package
uv run mkdocs serve                       # local docs

Contributions welcome -- see Contributing.

License

MIT