Guides
PubMed API (E-utilities): search, fetch abstracts, and stay under the rate limit
The PubMed API is NCBI’s E-utilities, a set of plain URLs under https://eutils.ncbi.nlm.nih.gov/entrez/eutils/: esearch.fcgi turns a PubMed query into a list of PMIDs, and efetch.fcgi returns the records for those PMIDs as text abstracts or XML. No key is needed. Without one, NCBI allows 3 requests a second from one IP address; a free NCBI API key raises that to 10. NCBI also asks every request to carry a tool parameter naming your software and an email parameter with the developer’s address.
Everything below was checked against NCBI’s E-utilities documentation and tested against the live service on November 18, 2026. The counts and PMIDs quoted are what the API returned that day.
The E-utilities at a glance
NCBI’s docs describe nine E-utilities. Four of them do almost all PubMed work.
| E-utility | What it does | Example |
|---|---|---|
| ESearch | Runs a query, returns the hit count and PMIDs | esearch.fcgi?db=pubmed&term=crispr+AND+2024[pdat]&retmode=json |
| EFetch | Returns full records: abstract text, MEDLINE or XML | efetch.fcgi?db=pubmed&id=29456894&rettype=abstract&retmode=text |
| ESummary | Returns short document summaries, including PMCID and DOI | esummary.fcgi?db=pubmed&id=29456894&retmode=json |
| ELink | Finds linked records, such as the PubMed Central copy of a PMID | elink.fcgi?dbfrom=pubmed&db=pmc&linkname=pubmed_pmc&id=29456894 |
| EPost | Uploads a list of PMIDs to the History server | epost.fcgi?db=pubmed&id=29456894,31428826 |
| EInfo | Lists databases, search fields and link names | einfo.fcgi?db=pubmed |
| ESpell, ECitMatch, EGQuery | Spelling suggestions, citation-to-PMID matching, global counts | ecitmatch.cgi?db=pubmed&rettype=xml&bdata=... |
Every URL above starts with https://eutils.ncbi.nlm.nih.gov/entrez/eutils/. ESearch, ESummary and ELink return XML by default and JSON with retmode=json. EFetch for PubMed returns text (rettype=abstract or rettype=medline with retmode=text) or XML (retmode=xml).
Searching PubMed for PMIDs with ESearch
ESearch takes the same query syntax as the PubMed website, including field tags like [ti], [au], [tiab] and [pdat]. URL-encode the brackets and spaces.
curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=crispr+AND+2024%5Bpdat%5D&retmax=5&retmode=json&tool=myapp&email=you@example.com"On November 18, 2026 this returned:
{"header":{"type":"esearch","version":"0.3"}, "esearchresult":{"count":"8772","retmax":"5","retstart":"0", "idlist":["42205224","41255389","40881775","40829017","40810089"], "translationset":[...], "querytranslation":"(\"clustered regularly interspaced short palindromic repeats\"[MeSH Terms] OR ... ) AND 2024/01/01:2024/12/31[Date - Publication]"}}A few things to know:
count,retmaxandretstartare strings in the JSON, not numbers. Convert them before you do arithmetic.retmaxdefaults to 20. Set it to what you need, or to 0 if you only want the count.querytranslationshows what PubMed actually searched. Here “crispr” was expanded to a MeSH term plus free-text variants. Check it when a count looks wrong.rettype=countreturns only the count:<Count>8772</Count>in XML, or{"esearchresult":{"count":"..."}}in JSON.- Sort and dates.
sorttakespub_date,Author,JournalNameorrelevance(the default, PubMed’s Best Match). To filter by date, usedatetype(pdat,edatormdat) withmindateandmaxdateinYYYY/MM/DD,YYYY/MMorYYYY, orreldate=60for the last 60 days.
Fetching abstracts as text or XML with EFetch
For people reading abstracts, ask for text:
curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed&id=29456894&rettype=abstract&retmode=text&tool=myapp&email=you@example.com"The text view gives the citation line, title, authors, affiliations and abstract, and ends with DOI: and PMID: lines, plus PMCID: when the article is in PubMed Central. It is formatted for reading, wrapped at about 80 characters, so do not parse it.
For code, ask for XML (retmode=xml, no rettype). The record for PMID 29456894 came back as a PubmedArticleSet declaring the PubMed DTD of January 1, 2025, and held:
MedlineCitation/PMID(29456894) andArticle/ArticleTitle(“The state of OA: a large-scale analysis of the prevalence and impact of Open Access articles.”)Abstract/AbstractText, one element per section. Structured abstracts carry aLabelattribute such asOBJECTIVEorBACKGROUND; join the sections yourself.PubmedData/ArticleIdList, with the record’s own IDs:pubmed29456894,pmcPMC5815332,doi10.7717/peerj.4375.
One trap: the same ArticleId element also appears inside the reference list, once per cited paper. A search for .//ArticleId on that record returned the DOIs of other papers. Read IDs from PubmedData/ArticleIdList/ArticleId only.
An unknown PMID is not an error either: efetch for id=99999999999 returned HTTP 200 with a body of just 1..
If you need many records, NCBI asks you to switch to HTTP POST once a list passes about 200 IDs.
Summaries and ID conversion with ESummary
ESummary is lighter than EFetch and has no abstract. It is the quickest way to get a title, journal, date and every ID for a PMID:
curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=29456894&retmode=json&tool=myapp&email=you@example.com"The result for 29456894 included "source":"PeerJ", "pubdate":"2018", "epubdate":"2018 Feb 13", nine authors from Piwowar H to Haustein S, "attributes":["Has Abstract"] and an articleids list with the PMC ID (PMC5815332) and DOI (10.7717/peerj.4375). Results are keyed by PMID under result, with the PMID order in result.uids.
Large result sets: the History server and the 9,999 cap
For more than a few hundred records, do not paste PMIDs into URLs. Run ESearch with usehistory=y, and NCBI keeps the whole result set on its History server and hands you two values to fetch it by:
curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=crispr+AND+2024%5Bpdat%5D&usehistory=y&retmax=0&tool=myapp&email=you@example.com"<eSearchResult><Count>8772</Count><RetMax>0</RetMax><RetStart>0</RetStart><QueryKey>1</QueryKey><WebEnv>MCID_6afde250a1f7dcf6ec0ce0d3</WebEnv><IdList/>...Then page through it with EFetch, holding retmax steady and moving retstart:
curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed&query_key=1&WebEnv=MCID_6afde250a1f7dcf6ec0ce0d3&retstart=0&retmax=200&retmode=xml&tool=myapp&email=you@example.com"The WebEnv string is yours to reuse: pass it to another ESearch with usehistory=y to add a second query, and combine sets in term with %231 AND %232 (query keys 1 and 2). NCBI’s parameter reference gives no lifetime for a WebEnv, so fetch soon after you search.
PubMed caps how deep a search can go. The docs say ESearch “can only retrieve the first 10,000 records” for PubMed and PMC. The live server is one stricter. Asking for retstart=10000 on a query with 72,829 hits returned HTTP 200 with this body:
{"esearchresult":{"ERROR":"Search Backend failed: Exception:\n'retstart' cannot be larger than 9998. For PubMed, ESearch can only retrieve the first 9,999 records matching the query. To obtain more than 9,999 PubMed records, consider using EDirect ..."}}To get more, split the query into date ranges that each return fewer than 9,999 records, use NCBI’s EDirect command-line tools, which batch automatically, or download the PubMed baseline files from the NLM. NCBI points large data-mining projects to the download.
Free full text in PubMed Central with ELink
PubMed holds citations and abstracts. Full text lives in PubMed Central (PMC), and ELink tells you whether a PMID has a PMC copy:
curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=pubmed&db=pmc&linkname=pubmed_pmc&id=29456894&retmode=json&tool=myapp&email=you@example.com"{"header":{"type":"elink","version":"0.3"}, "linksets":[{"dbfrom":"pubmed","ids":["29456894"], "linksetdbs":[{"dbto":"pmc","linkname":"pubmed_pmc","links":["5815332"]}]}]}The link is the numeric PMC ID; prefix PMC to get PMC5815332. No linksetdbs means no PMC copy. For several PMIDs, send one id= parameter per PMID (id=1&id=2) to get one linkset each; a comma list merges them into one set.
A PMC copy is free to read, but not every PMC article may be reused or text-mined, and PMC names the routes machines may use. Our guide to legal open-access full text for agents covers the PMC BioC API, the PMC cloud bucket, Europe PMC and licence checks. For papers outside PMC, cmd=prlinks lists the publisher’s full-text link.
Rate limits, API keys, and the tool and email parameters
NCBI’s usage rules, from chapter 2 of the E-utilities help:
| Rule | Without a key | With a key |
|---|---|---|
| Requests per second | 3 per IP address | 10 by default; higher on request to NCBI |
| Large jobs | Weekends, or 9:00 PM to 5:00 AM Eastern on weekdays | Same |
tool |
Name of your software, no spaces | Same |
email |
The developer’s real address, not your end user’s | Same |
| Over the limit | An error, and repeated abuse can get the IP blocked | Same |
Getting a key. Sign in to an NCBI account, open its Settings page and create an API key there. Add it to every request as api_key=.... Each account has one key, and making a new one cancels the old one. Keep it out of code you publish; read it from an environment variable.
tool and email. NCBI uses the email only to contact you before blocking traffic that breaks its rules, and says it will try that before it blocks. Send your own address, for example &tool=myapp&email=you@example.com. It must be a developer address, not a user of your app. The 2022 chapter also says a blocked IP gets service back only after its tool and email are registered with NCBI (by writing to eutilities@ncbi.nlm.nih.gov), and encourages registering early.
Where the limit is counted. By IP address without a key, and by key with one, so every script and MCP server on one machine or one key shares a single budget. Each response carries the count in headers: X-Ratelimit-Limit: 3 and X-Ratelimit-Remaining: 2 on our keyless calls.
Big jobs. Use the History server and fetch several hundred records per EFetch call, as NCBI suggests, instead of one call per PMID. At 3 requests a second, 9,000 records in batches of 200 take 46 requests, about 16 seconds of pacing.
429 errors and other real error bodies
To see the limit, we sent 5 requests at once with no key. Three came back 200, with X-Ratelimit-Remaining counting 2, 1, 0. The other two got:
HTTP/1.1 429 Too Many RequestsRetry-After: 2Content-Type: application/jsonX-Ratelimit-Remaining: 0
{"error":"API rate limit exceeded","api-key":"203.0.113.7","count":"4","limit":"3"}Without a key, the api-key field holds your IP address (we replaced ours). The fix is to wait the Retry-After seconds, then retry, and to pace calls at about 0.34 seconds apart without a key or 0.1 seconds with one.
Not every error is a 4xx. ESearch reports most problems inside a 200 response, so check for an ERROR key:
| Status | Body (abridged) | Cause | Fix |
|---|---|---|---|
| 429 | {"error":"API rate limit exceeded","api-key":"<your IP or key>","count":"4","limit":"3"}, Retry-After: 2 |
More than 3 requests a second without a key | Wait Retry-After seconds; pace requests; add a key |
| 400 | {"error":"API key invalid","api-key":"notarealkey","type":"invalid","status":"unknown"} |
Wrong or cancelled api_key |
Copy the current key from your NCBI account settings |
| 200 | {"esearchresult":{"ERROR":"Invalid db name specified: pubmedx"}} |
Misspelled db |
Use db=pubmed |
| 200 | {"esearchresult":{"ERROR":"Search Backend failed: Exception:\n'retstart' cannot be larger than 9998. ..."}} |
Paging past record 9,999 | Split the query by date, or use EDirect |
| 200 | 1. and nothing else |
EFetch for a PMID that does not exist | Check the PMID with ESummary |
Python: search, fetch and link in one script
This uses only requests and the standard library. It searches with the History server, fetches XML in batches, parses PMID, year, DOI, title and abstract, checks PMC for free full text, paces itself under the limit and retries on 429.
import osimport timeimport xml.etree.ElementTree as ET
import requests
BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"API_KEY = os.environ.get("NCBI_API_KEY") # optionalCOMMON = {"tool": "myapp", "email": "you@example.com"}if API_KEY: COMMON["api_key"] = API_KEYPAUSE = 0.11 if API_KEY else 0.34 # 10/s with a key, 3/s without
session = requests.Session()
def eutil(name, **params): """Call one E-utility, wait between calls, retry on 429.""" for attempt in range(5): time.sleep(PAUSE) r = session.get(f"{BASE}/{name}.fcgi", params={**COMMON, **params}, timeout=60) if r.status_code == 429: time.sleep(int(r.headers.get("Retry-After", "2"))) continue r.raise_for_status() return r raise RuntimeError(f"{name}: still rate limited after 5 tries")
def search(term, max_records=6, batch=3): # 1. ESearch: count the hits and park the PMIDs on the History server r = eutil("esearch", db="pubmed", term=term, usehistory="y", retmax=0, retmode="json") result = r.json()["esearchresult"] if "ERROR" in result: raise RuntimeError(result["ERROR"]) count = int(result["count"]) webenv, query_key = result["webenv"], result["querykey"] print(f"{count} records match")
# 2. EFetch: pull the records in batches from the History server for start in range(0, min(count, max_records), batch): r = eutil("efetch", db="pubmed", WebEnv=webenv, query_key=query_key, retstart=start, retmax=batch, retmode="xml") root = ET.fromstring(r.content) for art in root.findall("PubmedArticle"): pmid = art.findtext("MedlineCitation/PMID") title = "".join(art.find(".//ArticleTitle").itertext()) year = art.findtext(".//JournalIssue/PubDate/Year") or "" doi = next((a.text for a in art.findall("PubmedData/ArticleIdList/ArticleId") if a.get("IdType") == "doi"), None) parts = [] for p in art.findall(".//Abstract/AbstractText"): label = p.get("Label") text = "".join(p.itertext()) parts.append(f"{label}: {text}" if label else text) yield {"pmid": pmid, "year": year, "doi": doi, "title": title, "abstract": " ".join(parts)}
def pmc_ids(pmids): """ELink: which of these PMIDs have a free full-text copy in PMC.""" r = eutil("elink", dbfrom="pubmed", db="pmc", linkname="pubmed_pmc", id=pmids, retmode="json") # one id= per PMID keeps them apart out = {} for linkset in r.json()["linksets"]: links = [l for db in linkset.get("linksetdbs", []) for l in db["links"]] out[linkset["ids"][0]] = "PMC" + links[0] if links else None return out
if __name__ == "__main__": records = list(search('"open access"[ti] AND citation*[ti] AND 2018:2020[pdat]')) free = pmc_ids([r["pmid"] for r in records]) for rec in records: print(rec["pmid"], rec["year"], free.get(rec["pmid"]) or "-", rec["title"][:70]) print(" ", rec["abstract"][:110])Run on November 18, 2026, it made four requests and printed:
4 records match31428826 2020 PMC6890612 Citation advantage for open access articles in European Radiology. OBJECTIVE: To investigate whether there is a difference in citation rate between open access and subscription31163966 2019 - [Compliance with ethical rules for scientific publishing in biomedical This study examined compliance with the criteria of transparency and best practice in scholarly publishing def30851265 2019 PMC6731171 Open Access Publishing and Subsequent Citations Among Articles in Majo BACKGROUND: While open access publishing among cardiovascular journals has increased in scope over the last de29892634 2018 PMC5993002 Citation analytics: Data exploration and comparative analyses of CiteS Citation is one of the important metrics that are used in measuring the relevance and the impact of research pFor real use, raise batch to 200 and max_records to what you need, up to 9,999.
If you would rather not write the client, Biopython’s Bio.Entrez module wraps the same calls. Its source says it keeps to 3 requests a second without a key and 10 with one, makes up to three tries on 429 and 5xx responses, sends tool=biopython by default and warns when Entrez.email is not set.
PubMed MCP servers
To let an AI assistant search PubMed, use an MCP server rather than writing tools yourself. The most complete open-source one is cyanheads/pubmed-mcp-server (168 stars, Apache-2.0, version 2.12.2 on npm, November 13, 2026). It has 12 tools across PubMed, PMC, Europe PMC and NIH iCite, takes an optional NCBI_API_KEY, and has an NCBI_ADMIN_EMAIL setting for the contact address NCBI asks for. Most desktop MCP clients take this entry:
{ "mcpServers": { "pubmed": { "command": "npx", "args": ["-y", "@cyanheads/pubmed-mcp-server"], "env": { "NCBI_API_KEY": "your-key", "NCBI_ADMIN_EMAIL": "you@example.com" } } }}The server’s calls count against the same per-IP or per-key limit as your own scripts. For the official no-sign-in PubMed connector, older servers and setup per client, see MCP servers for research data. For trial registrations rather than papers, see the ClinicalTrials.gov API guide.
Hyperresearch’s Answers reads PubMed among its 120+ structured sources and quotes the record it cites.
Sources
- Entrez Programming Utilities Help, book contents: https://www.ncbi.nlm.nih.gov/books/NBK25501/
- A General Introduction to the E-utilities (usage guidelines, API keys; last updated November 17, 2022): https://www.ncbi.nlm.nih.gov/books/NBK25497/
- The E-utilities In-Depth: Parameters, Syntax and More (last updated March 4, 2026): https://www.ncbi.nlm.nih.gov/books/NBK25499/
- Entrez Direct (EDirect): https://www.ncbi.nlm.nih.gov/books/NBK179288/
- PubMed and MEDLINE download: https://www.nlm.nih.gov/databases/download/pubmed_medline.html
- Live E-utilities responses, November 18, 2026: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
- Biopython
Bio.Entrezsource: https://github.com/biopython/biopython/blob/master/Bio/Entrez/__init__.py - cyanheads/pubmed-mcp-server README: https://github.com/cyanheads/pubmed-mcp-server
