Skills › Scientific Agent Skills › paper-lookup › pubmed.md

pubmed.md

130 lines · skills/paper-lookup/references/pubmed.md at 5f2bc03

1# PubMed (NCBI E-utilities)

3PubMed provides citations, abstracts, and metadata for 37M+ biomedical and life science articles. It does NOT contain full text -- for that, use PMC.

PubMed (NCBI E-utilities)

PubMed provides citations, abstracts, and metadata for 37M+ biomedical and life science articles. It does NOT contain full text -- for that, use PMC.

Raw lines 1 to 4

5## Base URL

7```

8https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

9```

Base URL

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

Raw lines 5 to 10

11## Authentication

13- **API key optional** but recommended. Without: 3 req/sec. With: 10 req/sec.

14- Pass as: `&api_key=YOUR_KEY`

15- Also include `&tool=your_app_name&email=your@email.com` on all requests.

Authentication

API key optional but recommended. Without: 3 req/sec. With: 10 req/sec.
Pass as: &api_key=YOUR_KEY
Also include &tool=your_app_name&email=your@email.com on all requests.

Raw lines 11 to 16

17## Key Endpoints

Key Endpoints

Raw lines 17 to 18

19### 1. eSearch -- Search and get PMIDs

21```

22GET /esearch.fcgi?db=pubmed&term={query}&retmode=json

23```

26|-----------|----------|---------|-------------|

27| `db` | Yes | -- | `pubmed` |

28| `term` | Yes | -- | Search query. Supports PubMed syntax: field tags `[AU]`, `[TI]`, `[TA]`, `[MH]` (MeSH), boolean AND/OR/NOT |

29| `retmax` | No | 20 | Max PMIDs returned (max 10,000) |

30| `retstart` | No | 0 | Pagination offset within the first 10,000 matching IDs |

31| `retmode` | No | `xml` | `json` or `xml` |

34| `datetype` | No | -- | `pdat` (publication), `mdat` (modification), `edat` (entrez) |

35| `mindate` / `maxdate` | No | -- | Date range `YYYY/MM/DD` |

36| `reldate` | No | -- | Items from last N days |

37| `usehistory` | No | -- | `y` to return `WebEnv`/`query_key`; does not bypass the PubMed/PMC ESearch 10,000-ID cap |

39**Large searches:** split the query into disjoint date intervals with fewer than 10,000 hits each, or use NCBI EDirect. Reconcile counts and deduplicate PMIDs across partitions; `retstart` alone cannot traverse a larger PubMed result.

41**Example:**

42```

43https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=CRISPR+gene+therapy&retmode=json&retmax=5&sort=pub_date

44```

46**Response:**

47```json

48{

49 "esearchresult": {

50 "count": "224107",

51 "retmax": "5",

52 "retstart": "0",

53 "idlist": ["39984857", "39984678", "39984543", "39984210", "39983901"]

54 }

55}

56```

1. eSearch -- Search and get PMIDs

GET /esearch.fcgi?db=pubmed&term={query}&retmode=json

Parameter	Required	Default	Description
`db`	Yes	--	`pubmed`
`term`	Yes	--	Search query. Supports PubMed syntax: field tags `[AU]`, `[TI]`, `[TA]`, `[MH]` (MeSH), boolean AND/OR/NOT
`retmax`	No	20	Max PMIDs returned (max 10,000)
`retstart`	No	0	Pagination offset within the first 10,000 matching IDs
`retmode`	No	`xml`	`json` or `xml`
`rettype`	No	`uilist`	`uilist` (IDs) or `count` (count only)
`sort`	No	Set explicitly	`relevance`, `pub_date`, `Author`, `JournalName`
`datetype`	No	--	`pdat` (publication), `mdat` (modification), `edat` (entrez)
`mindate` / `maxdate`	No	--	Date range `YYYY/MM/DD`
`reldate`	No	--	Items from last N days
`usehistory`	No	--	`y` to return `WebEnv`/`query_key`; does not bypass the PubMed/PMC ESearch 10,000-ID cap

Large searches: split the query into disjoint date intervals with fewer than 10,000 hits each, or use NCBI EDirect. Reconcile counts and deduplicate PMIDs across partitions; retstart alone cannot traverse a larger PubMed result.

Example:

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=CRISPR+gene+therapy&retmode=json&retmax=5&sort=pub_date

Response:

{
  "esearchresult": {
    "count": "224107",
    "retmax": "5",
    "retstart": "0",
    "idlist": ["39984857", "39984678", "39984543", "39984210", "39983901"]
  }
}

Raw lines 19 to 57

58### 2. eSummary -- Get document summaries

60```

61GET /esummary.fcgi?db=pubmed&id={pmids}&retmode=json

62```

64| Parameter | Required | Description |

65|-----------|----------|-------------|

66| `db` | Yes | `pubmed` |

67| `id` | Yes* | Comma-separated PMIDs; prefer POST above about 200 IDs. Alternatively supply `WebEnv` and `query_key` |

68| `retmode` | No | `json` or `xml` |

70**Example:**

71```

72https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=39984857,39984678&retmode=json

73```

75**Response fields:** `uid`, `pubdate`, `source` (journal), `authors`, `title`, `volume`, `issue`, `pages`, `fulljournalname`, `elocationid` (DOI), `articleids` (PMC, DOI, etc.), `pubtype`, `pmcrefcount`

2. eSummary -- Get document summaries

GET /esummary.fcgi?db=pubmed&id={pmids}&retmode=json

Parameter	Required	Description
`db`	Yes	`pubmed`
`id`	Yes*	Comma-separated PMIDs; prefer POST above about 200 IDs. Alternatively supply `WebEnv` and `query_key`
`retmode`	No	`json` or `xml`

Example:

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=39984857,39984678&retmode=json

Response fields: uid, pubdate, source (journal), authors, title, volume, issue, pages, fulljournalname, elocationid (DOI), articleids (PMC, DOI, etc.), pubtype, pmcrefcount

Raw lines 58 to 76

77### 3. eFetch -- Retrieve full records (abstracts, MEDLINE)

79```

80GET /efetch.fcgi?db=pubmed&id={pmids}&rettype={type}&retmode={mode}

81```

83| rettype | retmode | Returns |

84|---------|---------|---------|

85| *(omit)* | `xml` | Full PubMed XML (citation + abstract) |

86| `medline` | `text` | MEDLINE format |

87| `abstract` | `text` | Plain text abstract |

88| `uilist` | `text` | PMID list |

90**Example -- get abstracts as XML:**

91```

92https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed&id=39984857&retmode=xml

93```

95Use POST for more than about 200 explicit IDs. The XML contains `<PubmedArticle>` with `<MedlineCitation>` (title, abstract, MeSH terms, authors) and `<PubmedData>` (article IDs, publication history).

3. eFetch -- Retrieve full records (abstracts, MEDLINE)

GET /efetch.fcgi?db=pubmed&id={pmids}&rettype={type}&retmode={mode}

rettype	retmode	Returns
(omit)	`xml`	Full PubMed XML (citation + abstract)
`medline`	`text`	MEDLINE format
`abstract`	`text`	Plain text abstract
`uilist`	`text`	PMID list

Example -- get abstracts as XML:

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed&id=39984857&retmode=xml

Use POST for more than about 200 explicit IDs. The XML contains <PubmedArticle> with <MedlineCitation> (title, abstract, MeSH terms, authors) and <PubmedData> (article IDs, publication history).

Raw lines 77 to 96

97### 4. eLink -- Find related articles

99```

100GET /elink.fcgi?dbfrom=pubmed&db=pubmed&id={pmid}&cmd=neighbor_score&retmode=json

101```

102

103For `cmd=neighbor_score`, read `linksets[].linksetdbs[].links[]` objects with `id` and `score` (confirmed in a public JSON response on 2026-09-30); relatedness is not a citation edge. `neighbor_score` is the documented scored-neighbor command.

104

4. eLink -- Find related articles

GET /elink.fcgi?dbfrom=pubmed&db=pubmed&id={pmid}&cmd=neighbor_score&retmode=json

For cmd=neighbor_score, read linksets[].linksetdbs[].links[] objects with id and score (confirmed in a public JSON response on 2026-09-30); relatedness is not a citation edge. neighbor_score is the documented scored-neighbor command.

Raw lines 97 to 104

105## Search Syntax Tips

106

107- **Field tags:** `aspirin[TI]` (title), `Smith J[AU]` (author), `Nature[TA]` (journal), `neoplasms[MH]` (MeSH heading)

108- **Boolean:** `CRISPR AND (therapy OR treatment)`

109- **Date range:** `2020/01/01:2024/12/31[PDAT]`

110- **Publication type:** `review[PT]`, `clinical trial[PT]`

111- **Organism:** `humans[MH]`, `mice[MH]`

112

Search Syntax Tips

Field tags: aspirin[TI] (title), Smith J[AU] (author), Nature[TA] (journal), neoplasms[MH] (MeSH heading)
Boolean: CRISPR AND (therapy OR treatment)
Date range: 2020/01/01:2024/12/31[PDAT]
Publication type: review[PT], clinical trial[PT]
Organism: humans[MH], mice[MH]

Raw lines 105 to 112

113## Rate Limits

114

115- **3 requests/second** without API key

116- **10 requests/second** with API key

117- Include `tool` and `email` parameters on every request

118- Large batch jobs should run outside peak hours (Mon-Fri 5AM-9PM ET)

119

Rate Limits

3 requests/second without API key
10 requests/second with API key
Include tool and email parameters on every request
Large batch jobs should run outside peak hours (Mon-Fri 5AM-9PM ET)

Raw lines 113 to 119

120## Error Format

121

122```json

123{"error": "API rate limit exceeded", "count": "11"}

124```

125

126HTTP 400 for bad requests, 429 for rate limiting.

127

Error Format

{"error": "API rate limit exceeded", "count": "11"}

HTTP 400 for bad requests, 429 for rate limiting.

Raw lines 120 to 127

128## Official sources reviewed 2026-09-30

129

130- https://www.ncbi.nlm.nih.gov/books/NBK25499/

Official sources reviewed 2026-09-30

https://www.ncbi.nlm.nih.gov/books/NBK25499/

Raw lines 128 to 130