Sources, coverage and limits
Observed on 2026-11-10. Services change: node scripts/scholarly.mjs status shows the
configuration in use and, after the first OpenAlex call, the budget left.
What each service is used for
| Service | Used for | Account | Cost |
|---|---|---|---|
Crossref (api.crossref.org) |
DOI metadata, search, deposited reference lists, retraction and correction notices | none | free |
| doi.org (content negotiation) | DOIs of every agency, including DataCite (arXiv, Zenodo, datasets); registry BibTeX | none | free |
arXiv (export.arxiv.org) |
preprint lookup and search, published DOI recorded by authors | none | free, one request per 3 s |
OpenAlex (api.openalex.org) |
citing works, related works, author works, open-access locations, retraction flag | optional key | small free budget |
Commands that never touch OpenAlex: verify-doi, resolve, verify-bib, parse-bib,
search (default source), get without --enrich, arxiv, references --source crossref,
cite, bibtex, retractions --no-openalex. Plain references uses Crossref and falls back to
OpenAlex only when the publisher deposited no list.
Commands that need OpenAlex: citations, related, author, oa (except for arXiv ids),
get --enrich, search --source openalex, references --source openalex, and retractions
by default (one single-record lookup per DOI).
The OpenAlex budget
Without a key, OpenAlex gives all clients behind one IP address a shared daily allowance. On
the test date it was 0.10 USD per day, with a single-record lookup priced at 0.0001 USD and a
search or list at 0.001 USD: about a hundred list calls a day, shared with everyone on the same
network. When it runs out, OpenAlex answers HTTP 429 and the tool returns the error code
rate_limited. Verification is unaffected: it runs on Crossref, arXiv and doi.org.
OpenAlex offers free keys with a larger allowance. Getting one requires an e-mail address, so
it is the user's decision: tell them the option exists, and do not register on their behalf.
When they have a key, they set OPENALEX_API_KEY in the environment of the tool.
Coverage
- Crossref: journal articles and proceedings from publishers that register DOIs with it; good for most journals since the 1990s and for digitised back files. Weak for books, book chapters of small presses, theses, reports, working papers and many regional journals.
- DataCite via doi.org: arXiv, Zenodo, institutional repositories, datasets. Lookup by DOI only; no search through this tool.
- arXiv: physics, mathematics, computer science, statistics, quantitative finance, economics and neighbouring fields.
- OpenAlex: the broadest index of the four, built by aggregation. Author names and affiliations can be noisy; author profiles sometimes merge or split people.
Not covered at all: full text, PubMed-only records without a DOI (use get pmid:<n> through
OpenAlex when it has them), legal materials, patents, most grey literature.
Reference lists
references <doi> returns the list the publisher deposited with Crossref. Many publishers
deposit them; some do not, and the list is then empty. Entries without a DOI are raw strings as
deposited, sometimes with errors. --source openalex returns only the references OpenAlex
could match to a work it indexes, so it can be shorter than the true list.
Retraction data
Crossref update notices carry type values such as retraction, correction,
expression_of_concern, with the DOI and date of the notice; since Crossref incorporated the
Retraction Watch database, many notices carry source: retraction-watch. OpenAlex exposes a
boolean is_retracted. The tool reports retracted when either says so. Both lag reality and
both have gaps: no_notice is an absence of evidence.
Request behaviour
- Client name:
scholarly-mcp/1.0. No name, address, host name or project detail. SCHOLARLY_MAILTO, when set by the operator, is added asmailto=to Crossref and OpenAlex requests only (their "polite pool" convention). It is unset by default.- Per-host limits built in: Crossref 3 concurrent requests, OpenAlex 2, arXiv 1 with a 3 s gap, doi.org 3.
- Timeout 20 s (
SCHOLARLY_TIMEOUT_MS). HTTP 429 and 5xx are retried up to three times with backoff; aRetry-Afterabove 30 s is not waited for. - Answers are cached in memory for 15 minutes within one process. Each command-line run is a new process, so nothing persists between runs.
- A registry outage produces
error,upstream_error,rate_limitedortimeout. It is never turned intonot_found.