OpenAlex Setup Guide

Beginner · 20–30 min · a free OpenAlex account for the API key

Google Scholar has no door for an agent. OpenAlex was built with one.

Overview

A reader of this site asked a question that the site did not answer: how do you search academic references with Claude Code, when Google Scholar keeps bouncing it? The short answer is OpenAlex, an open catalog of the global research system with a free API, an official command-line tool, and a help center written to be read by agents as much as by people. It is the place to start.

Scholar is a web page for human eyes. It publishes no API, blocks automated access, and an agent that scrapes it is both fragile and in breach of the terms. OpenAlex is the opposite kind of object: plain HTTPS requests that return JSON, a documented filter language, and a quick reference written for LLM agents alongside an OpenAPI spec and an llms.txt index. An agent given the key and the URL needs no further instruction.

Where it sits in the pipeline from this site's case study:

  research question
        |
        v
+-------+--------+   search / filter / cite   +----------+
| Coding agent   |-------------------------->| OpenAlex |
| Claude Code,   |<--------------------------| API, CLI |
| Codex, Kimi    |  DOIs, metadata, OA PDFs  +----------+
+-------+--------+
        |
        v
  candidate set
        |
   +----+-----+
   | You      |  screen against the protocol
   +----+-----+
        |
        v
    Zotero  ---->  MinerU  ---->  /00_literature_files/
   library         PDF -> md      ready for the agent

Research Rabbit stays the human eye on the citation network. Zotero stays the library of record. MinerU turns the PDFs into Markdown the agent can read. OpenAlex is the layer the agent itself can query.

Step 1: get a free key

Casual use needs no key at all: paste a request into a browser or curl it and JSON comes back. For anything an agent does, get the key, because agents make many requests and the keyless budget runs out fast.

1. Create an account at openalex.org (about 30 seconds).
2. Copy your key from openalex.org/settings/api.
3. Store it as an environment variable the agent can read:

echo 'export OPENALEX_API_KEY="your_key_here"' >> ~/.zshrc
source ~/.zshrc

setx OPENALEX_API_KEY "your_key_here"

What the key buys, per OpenAlex's own pricing and authentication pages:

• Every free account gets $1 of API usage per day, with no payment method required. Without a key the daily allowance is a tenth of that.
• A search request costs $1 per 1,000 calls. A list or filter request costs $0.10 per 1,000. Looking up one work by ID is free. Downloading a PDF costs $0.01 each.
• Two things return 429 Too Many Requests: exceeding the daily budget, or more than 100 requests per second.

In practice, a day's free allowance covers a thousand searches or a hundred PDF downloads, which is more than one systematic review's candidate search needs. Check the pricing page before a large batch; the numbers above are OpenAlex's to change.

Step 2: let the agent call the API

The API base is https://api.openalex.org. One request shows the shape of the whole thing:

curl -H "Authorization: Bearer $OPENALEX_API_KEY" \
  "https://api.openalex.org/works\
?search=organizational%20scaling\
&filter=publication_year:2020-2025,type:article,primary_location.source.type:journal\
&sort=cited_by_count:desc\
&per_page=25\
&select=id,doi,title,publication_year,cited_by_count,primary_location,abstract_inverted_index"

The parameters that matter for a literature search:

Two things worth knowing before the agent runs. Abstracts arrive as an inverted index (abstract_inverted_index), a word-to-positions map rather than a paragraph; any agent can rebuild the text from it, so ask for that explicitly if you want readable abstracts in the output. And citation chasing is built in: a work's referenced_works lists what it cites, and filter=cites:W... lists what cites it. That is forward and backward citation tracking as two requests, the step the SLR workflow otherwise does by hand from a Research Rabbit export.

You do not need to learn the API yourself. A prompt that names the constraints, the fields, and what to log is enough; OpenAlex documents itself for agents, and the help center is one fetch away when the agent is unsure. Two things the prompt must say, because the defaults get them wrong: type:article is not peer review (it is OpenAlex's class for original research, and the journal-source filter is a metadata proxy that screening still has to confirm), and the key must stay out of the logged URL.

Search OpenAlex for journal articles published 2020-2025 on
organizational scaling and scalability. Use the search parameter;
filter to type:article and primary_location.source.type:journal
(a proxy for peer review, which we confirm at screening); page with
cursor=*; select id, doi, title, publication_year, cited_by_count,
primary_location, and abstract_inverted_index. Rebuild each abstract
from the inverted index and leave the cell empty when it is null.

Read OPENALEX_API_KEY from the environment and send it only as a
bearer header. Never write the key into any file.

Write one row per work to 01_search_and_screening/openalex_candidates.csv.
Record the request URL without credentials, the date, the total count,
and any extra requests you made in 01_search_and_screening/search_log.md.

The agent will write a short script for this. Let it. A throwaway script that logs its own query is a better record than a series of chat turns, and it is the same move the PDF conversion guide recommends: ask for the script, keep the script.

Step 3: the official CLI for bulk pulls

OpenAlex ships a command-line tool, openalex-official, for pulling work metadata and open-access full text at volume. It handles parallel downloads, checkpointing, and rate limiting. It is a downloader, not a search tool: find the works with the API in Step 2, then hand their IDs or DOIs to the CLI.

Install (Python 3.9 or later):

uv tool install openalex-official
openalex status

pip install openalex-official
openalex status

openalex status confirms the key it found in OPENALEX_API_KEY and reports the credit remaining. Then:

# Metadata for every article matching a filter
openalex download --output ./openalex --filter "publication_year:2020-2025,type:article,fulltext.search:organizational scaling"

# Metadata plus open-access PDFs and TEI XML for a list of DOIs from Zotero
cat dois.txt | openalex download --output ./openalex --stdin --content pdf,xml

# Specific works by OpenAlex ID or DOI
openalex download --output ./openalex --ids "W2741809807,10.1038/nature12373"

What lands on disk:

openalex/
├── W2741809807.json          # metadata, always
├── W2741809807.pdf           # with --content pdf, open-access copies only
├── W2741809807.tei.xml       # with --content xml
├── .openalex-checkpoint.json # progress; rerun the same command to resume
└── openalex-download.log

Interrupted runs resume from the checkpoint; --fresh starts over. PDFs come back only for works OpenAlex has an open-access copy of. For everything else the JSON still arrives, and your library's subscription is still the route to the full text.

Step 4: into the pipeline

1. DOIs into Zotero. In Zotero, use Add Item by Identifier (the magic wand) with a DOI, or paste a list of DOIs one per line. Zotero fetches the metadata; Better BibTeX assigns the citation key. See the Zotero guide.
2. PDFs into Markdown. Run the downloaded PDFs through MinerU or the PDF conversion guide, and file the results in /00_literature_files/ named by citation key.
3. Screening. The candidate CSV goes to /01_search_and_screening/, and the /screen command in the SLR workflow runs against it. You make the include and exclude decisions; the agent applies your criteria and shows its reasoning.

What it is for, and what it is not

The second item on the left is the one that changes daily practice. When an AI writes a citation you do not recognize, resolving its DOI through OpenAlex is faster than a Scholar search and can be done by the same agent that wrote it. The verification protocol still applies; this just shortens the second level of it.

Part of Research Memex

• Research Scanner queries OpenAlex, Semantic Scholar, and arXiv on a schedule, so a research question keeps meeting literature it did not go looking for.
• Building an SLR with Claude Code is where the candidate set goes next.
• Session 2 of the systematic review case study places this beside Research Rabbit and Zotero in the discovery step.

External references

• OpenAlex help center, including the quickstart and the LLM quick reference
• OpenAlex CLI and its source
• API pricing