ai4protein OpenAlex
Overview
OpenAlex is a free index of >250M scholarly works built atop the Microsoft Academic Graph's successor. No API key required for the polite pool. Optional OPENALEX_EMAIL / USER_EMAIL env var → priority routing; OPENALEX_API_KEY env var → premium pool with higher limits.
Project Tools (VenusFactory2)
| Tool | Args | Returns | Description |
|---|---|---|---|
| download_openalex_entries_by_query | entity_type (required: works | authors | sources | institutions | topics | concepts | publishers | funders | ...), out_dir, search (free-text keyword), filter_expr (OpenAlex filter syntax, e.g. authorships.author.id:A123,publication_year:>2020), sort (e.g. cited_by_count:desc), per_page (default 25, max 200), page (default 1), timeout |
rich JSON envelope; saved JSON page at file_info.file_path; biological_metadata.total_count + result_count + next_page hint |
Search OpenAlex. |
| download_openalex_entry_by_id | entity_type, openalex_id (e.g. W3177828909, A5089215617, or full openalex.org URL), out_dir, timeout |
rich JSON envelope; full entity JSON at file_info.file_path; biological_metadata extracts display_name, cited_by_count, publication_year, doi |
Fetch a single entity by ID. |
When to Use This Skill
- "Find papers about X" / "what's the most cited paper on Y" → search
workswithsort=cited_by_count:desc - "Who is the most prolific author in topic X" → search
authorswithfilter_expr=topics.id:T... - "Get me the full record for [DOI/work ID]" →
download_openalex_entry_by_idonworks - "What's institution X publishing about lately" → search
workswithfilter_expr=authorships.institutions.id:I...,publication_year:2024
Filter Syntax Cheatsheet
Filters are comma-separated for AND, | inside a value for OR. Examples:
| Filter | Effect |
|---|---|
publication_year:2023 |
exact year |
publication_year:>2020 |
year > 2020 |
from_publication_date:2023-01-01 |
inclusive lower bound |
cited_by_count:>100 |
well-cited papers |
authorships.author.id:A5089215617 |
papers by a given author |
authorships.institutions.id:I4210090411 |
papers from a given institution (I4210090411 = DeepMind) |
topics.id:T11444 |
papers in a specific topic |
is_oa:true |
open access only |
type:journal-article |
filter by work type |
doi:10.1038/s41586-021-03819-2 |
exact DOI lookup |
ID Prefixes
W= Work (paper)A= AuthorS= Source (journal/conference/book/repo)I= InstitutionT= TopicC= ConceptP= PublisherF= Funder
Pagination
- Set
per_page≤ 200 and walkpage=1, 2, ...untilbiological_metadata.next_pageisNone. - For deep paging (>10k results), use OpenAlex's cursor pagination instead — out of scope for this tool; download the first page, inspect
meta.next_cursor, then drive the cursor manually.
Common Mistakes
per_page=1000: max is 200. Set to 200 then paginate.- Wrong entity prefix:
download_openalex_entry_by_id(entity_type='works', openalex_id='A123...')will 404 — the prefixAsays author, not work. - Filtering without an entity context:
filter_expr=author.id:A123makes no sense forentity_type=authors(useid:A123instead). - Free-text vs filter confusion:
search="cited_by_count desc"won't sort — use thesortparameter.
References
- OpenAlex docs
- Entity-type filter ref (one page per entity type)
- Get an OpenAlex API key (optional)