NewAnswers MCP: one question, one checked answer for your agent.See how it works

Guides

PubMed API (E-utilities): search, fetch abstracts, and stay under the rate limit

By , founder of HyperresearchPublished

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.

Terminal window
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, retmax and retstart are strings in the JSON, not numbers. Convert them before you do arithmetic.
  • retmax defaults to 20. Set it to what you need, or to 0 if you only want the count.
  • querytranslation shows what PubMed actually searched. Here “crispr” was expanded to a MeSH term plus free-text variants. Check it when a count looks wrong.
  • rettype=count returns only the count: <Count>8772</Count> in XML, or {"esearchresult":{"count":"..."}} in JSON.
  • Sort and dates. sort takes pub_date, Author, JournalName or relevance (the default, PubMed’s Best Match). To filter by date, use datetype (pdat, edat or mdat) with mindate and maxdate in YYYY/MM/DD, YYYY/MM or YYYY, or reldate=60 for the last 60 days.

Fetching abstracts as text or XML with EFetch

For people reading abstracts, ask for text:

Terminal window
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) and Article/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 a Label attribute such as OBJECTIVE or BACKGROUND; join the sections yourself.
  • PubmedData/ArticleIdList, with the record’s own IDs: pubmed 29456894, pmc PMC5815332, doi 10.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:

Terminal window
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:

Terminal window
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:

Terminal window
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.

PubMed holds citations and abstracts. Full text lives in PubMed Central (PMC), and ELink tells you whether a PMID has a PMC copy:

Terminal window
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 Requests
Retry-After: 2
Content-Type: application/json
X-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

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 os
import time
import xml.etree.ElementTree as ET
import requests
BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
API_KEY = os.environ.get("NCBI_API_KEY") # optional
COMMON = {"tool": "myapp", "email": "you@example.com"}
if API_KEY:
COMMON["api_key"] = API_KEY
PAUSE = 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 match
31428826 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 subscription
31163966 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 def
30851265 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 de
29892634 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 p

For 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