# 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.

```bash
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:

```json
{"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:

```bash
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:

```bash
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:

```bash
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"
```

```xml
<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`:

```bash
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:

```json
{"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:

```bash
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"
```

```json
{"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](/guides/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
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 |

## 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.

```python
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:

```text
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](https://github.com/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:

```json
{
  "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](/guides/research-data-mcp-servers). For trial registrations rather than papers, see the [ClinicalTrials.gov API](/guides/clinicaltrials-gov-api) guide.

Hyperresearch's [Answers](/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.Entrez` source: https://github.com/biopython/biopython/blob/master/Bio/Entrez/__init__.py
- cyanheads/pubmed-mcp-server README: https://github.com/cyanheads/pubmed-mcp-server
