OpenAlex API: Search scholarly papers
Searches OpenAlex scholarly works by topic, with optional institution, publication-year and open-access filters, ranked by relevance, citations or newest date.
Unofficial. Not affiliated with or endorsed by OpenAlex.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Sort optional
sort Order of results, for example most_cited.
relevance (default)
One of
relevance,most_cited,newest.- Query, required
query Topic words to find in scholarly works, for example microplastics in drinking water.
microplastics in drinking water
- End Year optional
end_year Latest publication year to include, for example 2024.
Not set
Whole number from 1 to 9999.
- Start Year optional
start_year Earliest publication year to include, for example 2020.
Not set
Whole number from 1 to 9999.
- Institution optional
institution Institution name (or OpenAlex institution ID) to filter author affiliations, for example Stanford University.
Not set
- Max Results optional
max_results Maximum papers to return, for example 20.
100
Whole number from 1 to 100. Default
20.- Open Access Only optional
open_access_only Include only open-access works, for example true.
false (default)
True or false.
Input as JSON
{ "query": "microplastics in drinking water", "max_results": 100}Output
{ "papers": [ { "title": "Microplastics in freshwaters and drinking water: Critical review and assessment of data quality", "venue": "Water Research", "authors": "Albert A. Koelmans, Nur Hazimah Mohamed Nor, Enya Hermsen, Merel Kooi, Svenja M. Mintenig, Jennifer De France", "doi_link": "https://doi.org/10.1016/j.watres.2019.02.054" , "open_access": true, "openalex_link": "https://openalex.org/W2918895016" , "citation_count": 2543, "openalex_work_id": "W2918895016", "publication_date": "2019-03-01", "publication_year": 2019, "free_full_text_link": "https://www.sciencedirect.com/science/article/pii/S0043135419301794/pdf" }, { "title": "Microplastics in drinking-water", "venue": "Socio-Environmental Systems Modeling", "authors": "P. Marsden, Koelmans, Bart, Julie Bourdon-Lacombe", "doi_link": "https://doi.org/10.60810/openumwelt-3831" , "open_access": true, "openalex_link": "https://openalex.org/W2972951570" , "citation_count": 253, "openalex_work_id": "W2972951570", "publication_date": "2019-01-01", "publication_year": 2019, "free_full_text_link": "https://edepot.wur.nl/498693" }, { "title": "Removal of microplastics via drinking water treatment: Current knowledge and future directions", "venue": "Chemosphere", "authors": "Maocai Shen, Biao Song, Yuan Cheng Zhu, Guangming Zeng, Yaxin Zhang, Yuanyuan Yang, Xiaofeng Wen, Ming Chen, Huan Yi", "doi_link": "https://doi.org/10.1016/j.chemosphere.2020.126612" , "open_access": false, "openalex_link": "https://openalex.org/W3015001951" , "citation_count": 406, "openalex_work_id": "W3015001951", "publication_date": "2020-03-30", "publication_year": 2020, "free_full_text_link": null } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"openalex.org/search_papers","input":{"query":"microplastics in drinking water","max_results":100}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "openalex.org/search_papers" , "input": { "query": "microplastics in drinking water", "max_results": 100 }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "openalex.org/search_papers" , "input": { "query": "microplastics in drinking water", "max_results": 100 } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run openalex.org/search_papers# with {"query":"microplastics in drinking water","max_results":100}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "query" ], "properties": { "sort": { "enum": [ "relevance", "most_cited", "newest" ], "type": "string", "default": "relevance", "description": "Order of results, for example most_cited." }, "query": { "type": "string", "minLength": 1, "description": "Topic words to find in scholarly works, for example microplastics in drinking water." }, "end_year": { "type": "integer", "maximum": 9999, "minimum": 1, "description": "Latest publication year to include, for example 2024." }, "start_year": { "type": "integer", "maximum": 9999, "minimum": 1, "description": "Earliest publication year to include, for example 2020." }, "institution": { "type": "string", "description": "Institution name (or OpenAlex institution ID) to filter author affiliations, for example Stanford University." }, "max_results": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "description": "Maximum papers to return, for example 20." }, "open_access_only": { "type": "boolean", "default": false, "description": "Include only open-access works, for example true." } }}Output schema
{ "type": "object", "required": [ "papers" ], "properties": { "papers": { "type": "array", "items": { "type": "object", "required": [ "title", "authors", "publication_year", "publication_date", "venue", "citation_count", "open_access", "free_full_text_link", "doi_link", "openalex_link", "openalex_work_id" ], "properties": { "title": { "type": [ "string", "null" ], "description": "Paper title." }, "venue": { "type": [ "string", "null" ], "description": "Journal, conference, or other publication venue." }, "authors": { "type": "string", "description": "Author names, separated by commas." }, "doi_link": { "type": [ "string", "null" ], "description": "DOI link, when known." }, "open_access": { "type": "boolean", "description": "Whether the work is open access." }, "openalex_link": { "type": "string", "description": "Paper page on OpenAlex." }, "citation_count": { "type": [ "integer", "null" ], "description": "Number of citations recorded." }, "openalex_work_id": { "type": "string", "description": "OpenAlex work identifier." }, "publication_date": { "type": [ "string", "null" ], "description": "Publication date in YYYY-MM-DD." }, "publication_year": { "type": [ "integer", "null" ], "description": "Year the work was published." }, "free_full_text_link": { "type": [ "string", "null" ], "description": "Link to a freely available full-text version, when known." } } }, "description": "Matching scholarly works." } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
openalex.org/search_papers- Returns
- title, authors, year, date, venue, citation count, open access, full-text link, DOI, OpenAlex link
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method openalex.org/search_papers with the inputs above.
Ask your agent
- Find the most cited papers on CRISPR off-target effects published between 2018 and 2023
- I need open-access research on microplastics in drinking water, newest first, limit to 15 results
- Search OpenAlex for papers on graphene battery anodes from researchers at MIT since 2020
- What are the latest scholarly articles about long COVID cognitive symptoms? Only free-to-read ones, please, with DOIs and full-text links
- Use openalex.org to pull 50 highly cited works on transformer models for protein structure prediction, authored at the University of Toronto
See more
All OpenAlex methodsSummarise an institution's research output from its name, including annual output, leading topics and authors. Annual citations count citations received by works published that year; leading authors are coauthors of institution-linked works, not necessarily employees.
openalex.org/get_institution_researchSearches Semantic Scholar for research papers in relevance order, with field of study, year range and open-access filters, returning AI one-sentence summaries, citations and free PDF links when available.
semanticscholar.org/search_papersFinds arXiv preprints by topic or title words, with optional author, subject, submission date range and sorting. Returns up to 100 papers with abstracts, subjects, dates and links.
arxiv.org/search_papersFinds bioRxiv and medRxiv preprints whose title, abstract or subject matches all topic words, within a posting date range, newest first. Adds published journal details when available.
biorxiv.org/search_preprintsFinds a paper on Semantic Scholar by title, DOI or Semantic Scholar link and returns its abstract, one-sentence summary, authors, publication details, citation counts and a free PDF link when there is one.
semanticscholar.org/get_paperFinds Open Library books by search words, optionally narrowed by author and subject, sorted by relevance or publication age. Returns work-level results; free_online means at least one edition is marked public or borrowable, not that a loan is available now.
openlibrary.org/search_booksFinds a legal free copy of a paper by title or DOI, with its best available link and other copies. If no free copy is indexed, the copy links are null.
unpaywall.org/get_free_versionFinds PubMed medical and life-science articles by topic, with publication details and free full-text links when PubMed confirms them.
pubmed.ncbi.nlm.nih.gov/search_articles