PubMed Literature Monitor (metadata only)

What it does

Search PubMed through NCBI E-utilities and collect bibliographic metadata. Monitor new PMIDs and changes to previously pushed articles. Results are deduplicated by PMID across queries, with all matching queries retained.

Abstracts are excluded because publishers or authors may hold copyright. The Actor never calls efetch and does not retrieve full text.

Input examples

Small search that includes unchanged articles.

{
  "queries": ["cancer immunotherapy"],
  "daysBack": 7,
  "maxPerQuery": 5,
  "maxItems": 5,
  "onlyNew": false
}

Monitor two searches with shared history.

{
  "queries": ["asthma[Title]", "asthma AND clinical trial[Publication Type]"],
  "daysBack": 7,
  "maxPerQuery": 50,
  "maxItems": 200,
  "onlyNew": true,
  "stateStoreName": "pubmed-monitor-state"
}

Input fields

Field	Default	Meaning
queries	["cancer immunotherapy"]	List of PubMed query strings. Query punctuation is preserved.
daysBack	7	Entrez-date window, sent as reldate with datetype=edat.
maxPerQuery	50	Search result cap per query, from 1 to 1000.
maxItems	200	Maximum article records pushed per run, from 1 to 10000.
onlyNew	true	Emit new or changed metadata only. Set false to include unchanged articles.
stateStoreName	pubmed-monitor-state	Named KV store holding history under SEEN.
contactEmail	cheechiawbot@mail.grokbot.com	Contact email sent to NCBI on every request.
apiKey	Unset	Optional secret NCBI key, sent as api_key. Never logged.

Every request includes tool=pubmed-monitor-apify. An API key does not increase this Actor's request rate.

Output sample

Illustrative metadata record. Missing strings are empty; missing lists are empty arrays. Source date strings are preserved.

{
  "pmid": "31452104",
  "title": "Molegro Virtual Docker for Docking.",
  "authors": ["Bitencourt-Ferreira G", "de Azevedo WF Jr"],
  "firstAuthor": "Bitencourt-Ferreira G",
  "lastAuthor": "de Azevedo WF Jr",
  "journal": "Methods in molecular biology (Clifton, N.J.)",
  "journalAbbrev": "Methods Mol Biol",
  "pubDate": "2019",
  "epubDate": "",
  "sortPubDate": "2019/01/01 00:00",
  "volume": "2053",
  "issue": "",
  "pages": "149-167",
  "doi": "10.1007/978-1-4939-9752-7_10",
  "pmcId": "",
  "publicationTypes": ["Journal Article"],
  "language": ["eng"],
  "pubmedUrl": "https://pubmed.ncbi.nlm.nih.gov/31452104/",
  "doiUrl": "https://doi.org/10.1007/978-1-4939-9752-7_10",
  "matchedQueries": ["molecular docking"],
  "checkedAt": "2026-10-20T08:00:00.000Z",
  "changeType": "new",
  "changedFields": []
}

The default dataset contains article records and uncharged error records. Error records contain an error message and context when available. The output links provide article and error column views. These views select columns; they do not filter rows.

The default KV store contains RUN_SUMMARY, with run timestamps, fetched/eligible/pushed counts, charge-limit status, and any run error.

How change tracking works

SEEN maps each pushed PMID to { fingerprint, fields }. The fingerprint is SHA-256 over stable JSON of the meaningful metadata. checkedAt, matchedQueries, and change markers are excluded, so a different search or check time does not create a metadata change.

An unseen PMID emits changeType: "new" and an empty changedFields. A different fingerprint emits "changed", with the names of changed metadata fields. Matching metadata emits "unchanged" and an empty list. With onlyNew: true, unchanged articles are skipped.

History is saved only after a successful article push. Records stopped by a charge limit remain eligible. Dataset pushes and KV writes are separate operations, so a crash between them can produce a duplicate on retry. Avoid overlapping runs that share the same store. Use separate store names for independent histories. Deleting SEEN resets history.

Pricing

$0.001 per article pushed, or $1 per 1,000 articles, using the article event. There is no run fee. Error records and skipped articles are not charged. With onlyNew: false, unchanged articles that are pushed incur the article event charge. The Actor stops at the charging manager's event limit. Local runs do not bill PPE events.

See PUBLISHING.md for the manual pricing configuration.

Limits

• Requests start at least 400 ms apart per host, at most 2.5 requests per second.
• At most 50 HTTP attempts per run, including retries. Later work may remain unprocessed.
• HTTP 429 and 5xx responses use exponential backoff and Retry-After. Requests time out after 30 seconds.
• Search uses esearch sorted by publication date. The date window uses entrez date, not publication date.
• Metadata uses esummary in batches of at most 200 PMIDs.
• This is a bounded search, not a complete PubMed archive or a guarantee of discovering every metadata revision. Older articles outside the date window are not checked unless the search window includes them.
• Field availability depends on NCBI metadata. State grows with successfully pushed PMIDs.

Terms and attribution

Data from PubMed, courtesy of the U.S. National Library of Medicine.

NCBI Disclaimer and Copyright notice applies. NLM requests acknowledgment when its information is reused. Government-created information is generally public domain, but third-party material can carry copyright restrictions. Users must follow the copyright holder's terms when reproducing, redistributing, or making commercial use of material. NLM does not claim copyright on PubMed abstracts; publishers or authors may. This Actor excludes abstracts entirely.

NCBI limits scripted access to three requests per second and requires contact email and tool parameters for distributed software. This Actor stays below that rate and caps runs below 100 requests. See TERMS.md for the recorded terms review.

Disclaimer

This Actor is unofficial and is not affiliated with or endorsed by NCBI, PubMed, or the U.S. National Library of Medicine. It uses public documented APIs only. It uses no source logos and requires no login. Metadata is not medical advice.

Local development

npm test
npm start

Node 20 or newer is required. npm start uses the sample live input and requires network access. Tests stub fetch with small E-utilities JSON fixtures and isolated local storage. No API credentials are needed for tests.

Run the real Actor offline with fixture responses through the fetch preload. This writes fixture records to local storage.

NODE_OPTIONS='--import=./test/offline-preload.js' APIFY_TOKEN='' APIFY_IS_AT_HOME='' npm start