# OpenAlex Setup Guide URL: https://research-memex.org/docs/implementation/foundational-setup/openalex-setup-guide Description: An open index with an API and a CLI is how a coding agent searches the literature without being bounced by Google Scholar. 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 [#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](https://openalex.org), 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](https://help.openalex.org/api/llm-quick-reference) 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: ```text title="diagram:agent-literature-search" 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](/docs/implementation/foundational-setup/research-rabbit-setup-guide) stays the human eye on the citation network. [Zotero](/docs/implementation/foundational-setup/zotero-setup-guide) stays the library of record. [MinerU](/docs/toolkit/mineru-mcp) turns the PDFs into Markdown the agent can read. OpenAlex is the layer the agent itself can query. ## Step 1: get a free key [#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](https://openalex.org) (about 30 seconds). 2. Copy your key from [openalex.org/settings/api](https://openalex.org/settings/api). 3. Store it as an environment variable the agent can read: ```bash title="macOS/Linux" echo 'export OPENALEX_API_KEY="your_key_here"' >> ~/.zshrc source ~/.zshrc ``` ```powershell title="Windows" setx OPENALEX_API_KEY "your_key_here" ``` What the key buys, per OpenAlex's own [pricing](https://help.openalex.org/access/pricing) and [authentication](https://help.openalex.org/api/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 [#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: ```bash 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: | Parameter | What it does | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search=` | Full-text search over title, abstract, and full text. The recommended way to search; the older `filter=default.search:` form is a deprecated alias | | `filter=` | Structured constraints, comma-separated: `publication_year:2020-2025`, `type:article`, `primary_location.source.type:journal`, `is_oa:true`, `cited_by_count:>100` | | `sort=` | `cited_by_count:desc`, `publication_date:desc`, or `relevance_score:desc` when searching | | `select=` | Return only the fields you name. Keeps the JSON small enough for an agent to hold many pages in context | | `per_page=` | Up to 100 results per request | | `cursor=*` | Start cursor paging; follow `meta.next_cursor` until it is `null`. Basic paging stops at 10,000 results, cursor paging does not | | `Authorization` | Send the key as a bearer header, as above. It is also accepted as an `api_key=` query parameter, but a key in the URL ends up in logs, shell history, and the search record; the header keeps it out of all three | 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](/docs/case-studies/systematic-reviews/claude-code-slr-workflow#62-forwardbackward-citation-tracking) 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](/docs/implementation/ai-environment-setup/ocr-pdf-conversion-guide) recommends: ask for the script, keep the script. ## Step 3: the official CLI for bulk pulls [#step-3-the-official-cli-for-bulk-pulls] OpenAlex ships a command-line tool, [`openalex-official`](https://github.com/ourresearch/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): ```bash title="uv" uv tool install openalex-official openalex status ``` ```bash title="pip" pip install openalex-official openalex status ``` `openalex status` confirms the key it found in `OPENALEX_API_KEY` and reports the credit remaining. Then: ```bash # 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 [#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](/docs/implementation/foundational-setup/zotero-setup-guide#61-import-from-databases). 2. PDFs into Markdown. Run the downloaded PDFs through [MinerU](/docs/toolkit/mineru-mcp) or the [PDF conversion guide](/docs/implementation/ai-environment-setup/ocr-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](/docs/case-studies/systematic-reviews/claude-code-slr-workflow#31-screening-command) 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 [#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](/docs/implementation/core-references/failure-museum) still applies; this just shortens the second level of it. ## Part of Research Memex [#part-of-research-memex] * [Research Scanner](/docs/toolkit/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](/docs/case-studies/systematic-reviews/claude-code-slr-workflow) is where the candidate set goes next. * [Session 2](/docs/case-studies/systematic-reviews/session-2-ai-powered-practice) of the systematic review case study places this beside Research Rabbit and Zotero in the discovery step. ## External references [#external-references] * [OpenAlex help center](https://help.openalex.org/), including the [quickstart](https://help.openalex.org/quickstart) and the [LLM quick reference](https://help.openalex.org/api/llm-quick-reference) * [OpenAlex CLI](https://help.openalex.org/access/cli/) and its [source](https://github.com/ourresearch/openalex-official) * [API pricing](https://help.openalex.org/access/pricing)