Repository Public Research preview
1# Sources, coverage and limits23Observed on 2026-11-10. Services change: `node scripts/scholarly.mjs status` shows the4configuration in use and, after the first OpenAlex call, the budget left.56## What each service is used for78| Service | Used for | Account | Cost |9|---|---|---|---|10| Crossref (`api.crossref.org`) | DOI metadata, search, deposited reference lists, retraction and correction notices | none | free |11| doi.org (content negotiation) | DOIs of every agency, including DataCite (arXiv, Zenodo, datasets); registry BibTeX | none | free |12| arXiv (`export.arxiv.org`) | preprint lookup and search, published DOI recorded by authors | none | free, one request per 3 s |13| OpenAlex (`api.openalex.org`) | citing works, related works, author works, open-access locations, retraction flag | optional key | small free budget |1415Commands that never touch OpenAlex: `verify-doi`, `resolve`, `verify-bib`, `parse-bib`,16`search` (default source), `get` without `--enrich`, `arxiv`, `references --source crossref`,17`cite`, `bibtex`, `retractions --no-openalex`. Plain `references` uses Crossref and falls back to18OpenAlex only when the publisher deposited no list.1920Commands that need OpenAlex: `citations`, `related`, `author`, `oa` (except for arXiv ids),21`get --enrich`, `search --source openalex`, `references --source openalex`, and `retractions`22by default (one single-record lookup per DOI).2324## The OpenAlex budget2526Without a key, OpenAlex gives all clients behind one IP address a shared daily allowance. On27the test date it was 0.10 USD per day, with a single-record lookup priced at 0.0001 USD and a28search or list at 0.001 USD: about a hundred list calls a day, shared with everyone on the same29network. When it runs out, OpenAlex answers HTTP 429 and the tool returns the error code30`rate_limited`. Verification is unaffected: it runs on Crossref, arXiv and doi.org.3132OpenAlex offers free keys with a larger allowance. Getting one requires an e-mail address, so33it is the user's decision: tell them the option exists, and do not register on their behalf.34When they have a key, they set `OPENALEX_API_KEY` in the environment of the tool.3536## Coverage3738- **Crossref**: journal articles and proceedings from publishers that register DOIs with it;39 good for most journals since the 1990s and for digitised back files. Weak for books, book40 chapters of small presses, theses, reports, working papers and many regional journals.41- **DataCite via doi.org**: arXiv, Zenodo, institutional repositories, datasets. Lookup by DOI42 only; no search through this tool.43- **arXiv**: physics, mathematics, computer science, statistics, quantitative finance,44 economics and neighbouring fields.45- **OpenAlex**: the broadest index of the four, built by aggregation. Author names and46 affiliations can be noisy; author profiles sometimes merge or split people.4748Not covered at all: full text, PubMed-only records without a DOI (use `get pmid:<n>` through49OpenAlex when it has them), legal materials, patents, most grey literature.5051## Reference lists5253`references <doi>` returns the list the publisher deposited with Crossref. Many publishers54deposit them; some do not, and the list is then empty. Entries without a DOI are raw strings as55deposited, sometimes with errors. `--source openalex` returns only the references OpenAlex56could match to a work it indexes, so it can be shorter than the true list.5758## Retraction data5960Crossref update notices carry `type` values such as `retraction`, `correction`,61`expression_of_concern`, with the DOI and date of the notice; since Crossref incorporated the62Retraction Watch database, many notices carry `source: retraction-watch`. OpenAlex exposes a63boolean `is_retracted`. The tool reports `retracted` when either says so. Both lag reality and64both have gaps: `no_notice` is an absence of evidence.6566## Request behaviour6768- Client name: `scholarly-mcp/1.0`. No name, address, host name or project detail.69- `SCHOLARLY_MAILTO`, when set by the operator, is added as `mailto=` to Crossref and OpenAlex70 requests only (their "polite pool" convention). It is unset by default.71- Per-host limits built in: Crossref 3 concurrent requests, OpenAlex 2, arXiv 1 with a 3 s gap,72 doi.org 3.73- Timeout 20 s (`SCHOLARLY_TIMEOUT_MS`). HTTP 429 and 5xx are retried up to three times with74 backoff; a `Retry-After` above 30 s is not waited for.75- Answers are cached in memory for 15 minutes within one process. Each command-line run is a76 new process, so nothing persists between runs.77- A registry outage produces `error`, `upstream_error`, `rate_limited` or `timeout`. It is never78 turned into `not_found`.79