Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.openalex.org/llms.txt

Use this file to discover all available pages before exploring further.

Semantic search returns works whose meaning is closest to your query, even when the wording differs. A query about “predicting drug toxicity from molecular structure” finds papers using “computational toxicology” or “QSAR” — words your search never mentioned. 
https://api.openalex.org/works?search.semantic=predicting drug toxicity from molecular structure

​
Long-text queries

Semantic search shines when you have a longer description — an abstract, a grant aim, or a paragraph from a paper you’re writing. The richer the input, the better the matches. 
# Paste your grant aim verbatim (URL-encoded)
https://api.openalex.org/works?search.semantic=We propose to integrate single-cell RNA-seq with spatial transcriptomics to map T-cell exhaustion in solid tumors and identify novel checkpoint targets.
Up to 2,000 characters are used for matching; longer input is truncated.

​
Combining with filters

Most filters and the select parameter work as usual: 
https://api.openalex.org/works?search.semantic=mRNA vaccine immunogenicity in older adults&filter=publication_year:>2020,is_oa:true&select=id,title,relevance_score
Two filters are not supported on semantic search — they would require pre-filtering hundreds of millions of vectors and time out:
  • last_known_institutions.country_code (and the country_code shorthand)
  • cited_by_count

​
How it works

OpenAlex embeds the title and abstract of every work using GTE Large EN, an open-source embedding model from Alibaba DAMO Academy, into a 1,024-dimensional vector. At query time we embed your query the same way and return the works closest by cosine similarity.

​
Limits

ConstraintValue
Max input length2,000 characters
Max results50 per query
Rate limit1 request per second
PricingSee pricing by endpoint
Only one search parameter is allowed per request: search, search.exact, or search.semantic.