Python tooling over the keyless bioRxiv API for searching and retrieving life-sciences preprints. Searches by keyword, author, date range, and category, returning structured JSON (titles, abstracts, DOIs, authors, versions), and downloads full-text PDFs.
\nFor published, peer-reviewed literature use alterlab-pubmed; for computer-science / physics / math preprints use alterlab-arxiv. bioRxiv covers biology subjects only. The same API also serves medRxiv (swap biorxiv for medrxiv in the endpoint path, e.g. /details/medrxiv/2025-03-21/2025-03-28?category=cardiovascular%20medicine); the bundled script targets bioRxiv, so query medRxiv with curl/requests directly.
The bioRxiv /details endpoint returns preprints by date range, 30 records per page. It accepts a server-side subject-category filter (?category=cell_biology), but has no keyword or author filter. So this tool:
--category to the server so only that subject is fetched, thenImplication: a wide date range means many API calls and a large download. Keep ranges as tight as the question allows, and use --category (cuts API calls) and --limit to bound the work.
Use this skill when:
\n| Scenario | \nUse Instead | \n
|---|---|
| Peer-reviewed, MeSH-indexed biomedical journal articles | \nalterlab-pubmed | \n
| CS / physics / math / quantitative-biology preprints on arXiv | \nalterlab-arxiv | \n
| Citation counts or cross-publisher bibliometrics for preprints | \nalterlab-openalex | \n
| Depositing your own preprint (server choice, license, versioning) | \nalterlab-preprint-deposition | \n
| Multi-database systematic review with PRISMA screening | \nalterlab-literature-review | \n
The script's only dependency is requests. Run it with uv so the dependency is provisioned on the fly:
uv run --with requests scripts/biorxiv_search.py --help\nThe python scripts/biorxiv_search.py ... invocations below are shorthand; substitute uv run --with requests scripts/biorxiv_search.py ... (or activate an environment that has requests).
Search for preprints containing specific keywords in titles, abstracts, or author lists.
\nBasic Usage:
\npython scripts/biorxiv_search.py \\\n --keywords \"CRISPR\" \"gene editing\" \\\n --start-date 2024-01-01 \\\n --end-date 2024-12-31 \\\n --output results.json\nWith Category Filter:
\npython scripts/biorxiv_search.py \\\n --keywords \"neural networks\" \"deep learning\" \\\n --days-back 180 \\\n --category neuroscience \\\n --output recent_neuroscience.json\nSearch Fields:\nKeyword matching is a case-insensitive substring match, and a paper matches if any keyword is found (OR semantics, not AND). By default keywords are searched in both title and abstract. Customize with --search-fields:
python scripts/biorxiv_search.py \\\n --keywords \"AlphaFold\" \\\n --search-fields title \\\n --days-back 365\nFind all papers by a specific author within a date range.
\nBasic Usage:
\npython scripts/biorxiv_search.py \\\n --author \"Smith\" \\\n --start-date 2023-01-01 \\\n --end-date 2024-12-31 \\\n --output smith_papers.json\nRecent Publications:
\n# Last year by default if no dates specified\npython scripts/biorxiv_search.py \\\n --author \"Johnson\" \\\n --output johnson_recent.json\nRetrieve all preprints posted within a specific date range.
\nBasic Usage:
\npython scripts/biorxiv_search.py \\\n --start-date 2024-01-01 \\\n --end-date 2024-01-31 \\\n --output january_2024.json\nWith Category Filter:
\npython scripts/biorxiv_search.py \\\n --start-date 2024-06-01 \\\n --end-date 2024-06-30 \\\n --category genomics \\\n --output genomics_june.json\nDays Back Shortcut:
\n# Last 30 days\npython scripts/biorxiv_search.py \\\n --days-back 30 \\\n --output last_month.json\nRetrieve detailed metadata for a specific preprint. bioRxiv DOIs come in two prefixes:\n10.1101/… for older preprints and 10.64898/… for preprints posted since the move to\nopenRxiv (December 2025), e.g. 10.64898/2026.08.28.747819. Both work with /details/\nand the www.biorxiv.org/content/ URLs; the script normalizes DOIs, doi.org links, and\ncontent URLs regardless of prefix. Don't hard-code 10.1101 in regexes or validators.
Basic Usage:
\npython scripts/biorxiv_search.py \\\n --doi \"10.1101/2024.01.15.123456\" \\\n --output paper_details.json\nFull DOI URLs Accepted (either prefix):
\npython scripts/biorxiv_search.py \\\n --doi \"https://doi.org/10.64898/2026.08.28.747819\"\nDownload the full-text PDF of any preprint.
\nBasic Usage:
\npython scripts/biorxiv_search.py \\\n --doi \"10.1101/2024.01.15.123456\" \\\n --download-pdf paper.pdf\nBatch Processing:\nFor multiple PDFs, extract DOIs from a search result JSON and download each paper:
\nimport json\nfrom biorxiv_search import BioRxivSearcher\n\n# Load search results\nwith open('results.json') as f:\n data = json.load(f)\n\nsearcher = BioRxivSearcher(verbose=True)\n\n# Download each paper\nfor i, paper in enumerate(data['results'][:10]): # First 10 papers\n doi = paper['doi']\n searcher.download_pdf(doi, f\"papers/paper_{i+1}.pdf\")\nFilter searches by bioRxiv subject categories:
\nanimal-behavior-and-cognitionbiochemistrybioengineeringbioinformaticsbiophysicscancer-biologycell-biologyclinical-trialsdevelopmental-biologyecologyepidemiologyevolutionary-biologygeneticsgenomicsimmunologymicrobiologymolecular-biologyneurosciencepaleontologypathologypharmacology-and-toxicologyphysiologyplant-biologyscientific-communication-and-educationsynthetic-biologysystems-biologyzoologyAll searches return structured JSON with the following format:
\n{\n \"query\": {\n \"keywords\": [\"CRISPR\"],\n \"start_date\": \"2024-01-01\",\n \"end_date\": \"2024-12-31\",\n \"category\": \"genomics\"\n },\n \"result_count\": 42,\n \"results\": [\n {\n \"doi\": \"10.1101/2024.01.15.123456\",\n \"title\": \"Paper Title Here\",\n \"authors\": \"Smith, J.; Doe, J.; Johnson, A.\",\n \"author_corresponding\": \"Smith J\",\n \"author_corresponding_institution\": \"University Example\",\n \"date\": \"2024-01-15\",\n \"version\": \"1\",\n \"type\": \"new results\",\n \"license\": \"cc_by\",\n \"category\": \"genomics\",\n \"abstract\": \"Full abstract text...\",\n \"pdf_url\": \"https://www.biorxiv.org/content/10.1101/2024.01.15.123456v1.full.pdf\",\n \"html_url\": \"https://www.biorxiv.org/content/10.1101/2024.01.15.123456v1\",\n \"jatsxml\": \"https://www.biorxiv.org/content/...\",\n \"published\": \"\"\n }\n ]\n}\npython scripts/biorxiv_search.py \\\n --keywords \"organoids\" \"tissue engineering\" \\\n --start-date 2023-01-01 \\\n --end-date 2024-12-31 \\\n --category bioengineering \\\n --output organoid_papers.json\nimport json\n\nwith open('organoid_papers.json') as f:\n data = json.load(f)\n\nprint(f\"Found {data['result_count']} papers\")\n\nfor paper in data['results'][:5]:\n print(f\"\\nTitle: {paper['title']}\")\n print(f\"Authors: {paper['authors']}\")\n print(f\"Date: {paper['date']}\")\n print(f\"DOI: {paper['doi']}\")\nfrom biorxiv_search import BioRxivSearcher\n\nsearcher = BioRxivSearcher()\nselected_dois = [\"10.1101/2024.01.15.123456\", \"10.1101/2024.02.20.789012\"]\n\nfor doi in selected_dois:\n filename = doi.replace(\"/\", \"_\").replace(\".\", \"_\") + \".pdf\"\n searcher.download_pdf(doi, f\"papers/{filename}\")\nTrack research trends by analyzing publication frequencies over time:
\npython scripts/biorxiv_search.py \\\n --keywords \"machine learning\" \\\n --start-date 2020-01-01 \\\n --end-date 2024-12-31 \\\n --category bioinformatics \\\n --output ml_trends.json\nThen analyze the temporal distribution in the results.
\nMonitor specific researchers' preprints:
\n# Track multiple authors (each run scans the whole window, so keep it short)\nfor author in Smith Johnson Williams; do\n python scripts/biorxiv_search.py \\\n --author \"$author\" \\\n --days-back 365 \\\n --output \"${author}_papers.json\"\ndone\nFor more complex workflows, import and use the BioRxivSearcher class directly:
from scripts.biorxiv_search import BioRxivSearcher\n\n# Initialize\nsearcher = BioRxivSearcher(verbose=True)\n\n# Multiple search operations\nkeywords_papers = searcher.search_by_keywords(\n keywords=[\"CRISPR\", \"gene editing\"],\n start_date=\"2024-01-01\",\n end_date=\"2024-12-31\",\n category=\"genomics\"\n)\n\nauthor_papers = searcher.search_by_author(\n author_name=\"Smith\",\n start_date=\"2023-01-01\",\n end_date=\"2024-12-31\"\n)\n\n# Get specific paper details\npaper = searcher.get_paper_details(\"10.1101/2024.01.15.123456\")\n\n# Download PDF\nsuccess = searcher.download_pdf(\n doi=\"10.1101/2024.01.15.123456\",\n output_path=\"paper.pdf\"\n)\n\n# Format results consistently\nformatted = searcher.format_result(paper, include_abstract=True)\nKeep date ranges tight: Because filtering is client-side, the tool paginates the entire range (30 records/page) before filtering. A single busy week is ~800 preprints (~27 API calls); a full year is tens of thousands. Narrow the range, or use --days-back for recency.
Filter by category: Use --category whenever the subject is known. It is sent to the server (?category=), so it cuts both the result set and the number of API calls (one busy week: ~1,270 preprints overall vs. ~80 in cell biology).
Cap with --limit: For pure date-range searches, --limit also stops pagination early, so it genuinely reduces API calls. For keyword/author searches the whole range must be scanned first, so --limit only trims the final list.
Respect rate limits: The script sleeps 0.5s between requests. There is no documented hard rate limit, but for large collections add more delay and cache results to JSON.
\nVersion tracking: Preprints can have multiple versions. DOI lookups return the latest version; download_pdf resolves the latest version automatically (pass version= to override). PDF/HTML URLs embed the version number. The published field of /details/ carries the journal DOI once the preprint is published (or NA) — use it rather than the per-DOI /pubs/ lookup, which returns nothing for 10.64898 DOIs.
PDF downloads can be throttled: PDFs come from www.biorxiv.org, which sits behind Cloudflare and may answer scripted requests with HTTP 429. Space downloads out, fall back to the html_url, and for bulk full text use bioRxiv's requester-pays text-mining bucket s3://biorxiv-src-monthly (MECA zip packages; see https://www.biorxiv.org/tdm).
Handle empty results: Check result_count. Empty results usually mean the date range had no matching papers, an over-narrow category, or transient API connectivity issues — not a silent truncation (pagination retrieves the full range).
Verbose mode for debugging: Use --verbose to see each paginated API request and the reported total.
from datetime import datetime, timedelta\nfrom scripts.biorxiv_search import BioRxivSearcher\n\n# Last quarter\nend_date = datetime.now()\nstart_date = end_date - timedelta(days=90)\n\npapers = BioRxivSearcher().search_by_date_range(\n start_date.strftime(\"%Y-%m-%d\"), end_date.strftime(\"%Y-%m-%d\"), category=\"genomics\"\n)\nLimit the number of results returned:
\npython scripts/biorxiv_search.py \\\n --keywords \"COVID-19\" \\\n --days-back 30 \\\n --limit 50 \\\n --output covid_top50.json\nWhen only metadata is needed:
\n# Note: Abstract inclusion is controlled in Python API\nfrom scripts.biorxiv_search import BioRxivSearcher\n\nsearcher = BioRxivSearcher()\npapers = searcher.search_by_keywords(keywords=[\"AI\"], days_back=30)\nformatted = [searcher.format_result(p, include_abstract=False) for p in papers]\nIntegrate search results into downstream analysis pipelines:
\nimport json\nimport pandas as pd\n\n# Load results\nwith open('results.json') as f:\n data = json.load(f)\n\n# Convert to DataFrame for analysis\ndf = pd.DataFrame(data['results'])\n\n# Analyze\nprint(f\"Total papers: {len(df)}\")\nprint(f\"Date range: {df['date'].min()} to {df['date'].max()}\")\nprint(f\"\\nTop authors by paper count:\")\nprint(df['authors'].str.split(';').explode().str.strip().value_counts().head(10))\n\n# Filter and export\nrecent = df[df['date'] >= '2024-06-01']\nrecent.to_csv('recent_papers.csv', index=False)\nFor detailed API specifications, endpoint documentation, and response schemas, refer to:
\nreferences/api_reference.md - Complete bioRxiv API documentationThe reference file includes:
\n