NIH RePORTER Award Monitor

First-seen + change-detection over the live NIH RePORTER research-award feed. NIH RePORTER is the U.S. government's authoritative record of the grants, contracts, and cooperative agreements the National Institutes of Health funds — who got funded, by which Institute/Center, for how much, on what topic. Farms republish the normalized award record as a static snapshot; nobody sells the delta. This Actor polls the v2 /v2/projects/search query API with a JSON criteria body, pages through meta.total (500 per page, capped at the 15,000-record search ceiling), snapshots a per-award fingerprint in the key-value store, and emits one record per newly-seen award plus a re-emit whenever a watched award changes — an award_amount revision (administrative supplement), a project_end_date extension (no-cost extension), or a later-added abstract / terms list. A snapshot of the whole portfolio becomes an operational "what got funded — or re-funded — in my field, since I last looked" alert stream.

Plain HTTPS calls to one clean REST/JSON host — no browser, no proxy, no login, no API key (the RePORTER API is keyless and public-domain). The documented rate limit is 1 request/second; the fetch layer paces to it. Data source: NIH RePORTER, U.S. government public domain (Title 17 U.S.C.).

Data courtesy of the NIH RePORTER API (U.S. National Institutes of Health).

Status: launch-ready (v0.1, unpublished by design). All layers are implemented and tested offline — the fetch/paginate/normalize layer (src/nih.js), the fingerprint diff (src/diff.js), the client filters (src/filters.js), the Actor entry (src/main.js), the unit + integration suites (test/), the compliance record (COMPLIANCE.md), and the pricing/listing drafts (docs/). This Actor is built, never published — no apify push, no on-platform pricing. See CHANGELOG.md for the slice history.

---

What it does

Each run resolves an award_notice_date delta window, builds the v2 search criteria body, and pages the /v2/projects/search query API (limit up to 500, offset until meta.total is exhausted or the 15,000-record ceiling is hit) under a 1 req/s token bucket with exponential backoff on 429/5xx. Each award is normalized to one flat award shape — application id, project + core project number, title, contact PI + investigators, organization, fiscal year, award amount, funding IC, project dates, abstract/terms — then diffed against the prior run's per-award fingerprint map to emit only what is new or changed.

• The delta, not the blob (the moat): NIH awards mutate after the notice — supplements revise the amount, no-cost extensions move the end date, abstracts land late. This emits exactly those transitions over a corpus everyone else republishes whole.
• Award identity done right: the diff keys on appl_id (the unique application id), so each award year is its own record and a supplement's amount revision is a first-class changed event — core_project_num groups an award's support years for the reader.
• Server-side + client filters: advanced_text_search, org_names, pi_names, agencies, fiscal_years, award_amount_range narrow the query at the API; text / IC / award-floor criteria are re-applied client-side as a belt-and-suspenders pass.
• Change monitor: monitorNewOnly persists the fingerprint map + the award-notice high-water-mark and, on the next scheduled run, emits only newly-seen or changed awards. A first run seeds the baseline (emits nothing).

Inputs

Input	Type	Notes
textSearch	string	RePORTER advanced_text_search over title/abstract/terms. Empty = all
orgNames	array	Grantee organization names (org_names, contains-match). Empty = all
piNames	array	PI names (pi_names any-name match). Empty = all
fundingIc	array	NIH IC / agency abbreviations (agencies, e.g. NCI, NIAID). Empty = all
fiscalYears	array	Fiscal years (fiscal_years, e.g. 2026). Empty = all in the window
awardAmountMin	integer	Minimum total award amount (award_amount_range.min_amount). 0 = no floor
since	string	Lower bound of the award_notice_date window (YYYY-MM-DD). Empty = recent trailing window
until	string	Optional upper bound (award_notice_date.to_date). Empty = now
monitorNewOnly	boolean	Diff vs the stored fingerprint map; emit only new/changed. Default: on
maxResults	integer	Cap total records returned (0 = no cap)
proxyConfiguration	object	Optional; the API is open and needs no proxy. Default: none

Output — one record per new / changed award

{
  "applId": 10812345,
  "projectNum": "5R01CA123456-04",
  "coreProjectNum": "R01CA123456",
  "title": "Mechanisms of Tumor Immune Evasion",
  "contactPi": "DOE, JANE",
  "investigators": ["DOE, JANE", "SMITH, JOHN"],
  "organization": "STANFORD UNIVERSITY",
  "fiscalYear": 2026,
  "awardAmount": 512340,
  "fundingIc": "NCI",
  "projectStartDate": "2023-04-01",
  "projectEndDate": "2027-03-31",
  "awardNoticeDate": "2026-04-15",
  "abstract": "This project investigates the mechanisms by which tumors evade immune surveillance...",
  "terms": ["Immunology", "Oncology", "T-Lymphocytes"],
  "detailUrl": "https://reporter.nih.gov/project-details/10812345",
  "changeType": "changed",
  "changedFields": ["awardAmount", "projectEndDate"],
  "attribution": "Data courtesy of the NIH RePORTER API (U.S. National Institutes of Health).",
  "fetchedAt": "2026-07-10T14:00:00.000Z"
}

applId (the unique application id) is the dedupe key. changeType is new (first-seen) or changed under monitorNewOnly, or listed in plain full-window mode (monitorNewOnly: false, no diff); changedFields lists the fingerprint fields that moved (empty for new/listed). An award whose abstract has not posted yet has abstract null, and the later null → present transition is a reported change. Every record carries the courtesy attribution string.

Control records (not charged)

Three non-award records may be pushed to signal run state. None triggers a project-returned charge:

Record	When	Shape
_baseline	First run (empty prior state): the fingerprint map is snapshotted as the baseline and no change events are emitted	{ "_baseline": true, "filters": {...}, "snapshotSize": N, "window": {...}, "message": "...", "fetchedAt": "..." }
_noData	A subsequent run whose delta is empty (no new/changed awards matched the filters)	{ "_noData": true, "filters": {...}, "message": "...", "fetchedAt": "..." }
_error	The query failed after retries, or the JSON envelope drifted / parse threw	{ "_error": true, "filters": {...}, "message": "...", "fetchedAt": "..." }

_baseline/_noData keep a zero-delta run green and auditable rather than pushing a silent empty dataset. A first run seeds the baseline and reports _baseline; subsequent runs report only true new/changed awards, or _noData when there were none.

Pricing (pay-per-event)

One project-returned event is charged per new/changed award record pushed to the dataset. Cost scales with the size of the delta, not runtime or window size. Use textSearch / fundingIc / fiscalYears / awardAmountMin / maxResults to keep spend proportional to signal. The intended price band and the reasoning behind the single-event model are in docs/PRICING.md — documented-only; the live $/event value is owner-gated / DEFERRED and no on-platform pricing is set in this build. (Live price shown on the Store page once published.)

Data source & attribution

All NIH RePORTER data is U.S. government public domain (Title 17 U.S.C.) — freely available, no fees, no licensing restrictions, no registration, no API key. Attribution is not a licence condition (unlike NVD's mandated string); we carry a courtesy source credit — "Data courtesy of the NIH RePORTER API (U.S. National Institutes of Health)." — on every record and in this README as good practice. Full compliance record: COMPLIANCE.md.

Maintenance notes

• POST query API, not a GET string. RePORTER takes a JSON criteria body at /v2/projects/search; paging is offset/limit against meta.total, not a query-string cursor. Confirm the exact v2 criteria field names + response envelope against the live schema when the fetch layer lands (slice 2) — this scaffold fixes the contract from documented shapes.
• 15,000-record search ceiling. offset + limit may not exceed ~15k; a broad query must be narrowed (fiscal year / IC / award-notice window), not paged past the cap. The paginator stops at the ceiling and surfaces truncation so the high-water-mark is not advanced past an incomplete pass.
• 1 req/sec rate limit. The fetch layer runs a token bucket sized to 1 request/second + exponential backoff on 429/5xx. There is no API key to raise it — the limit is fixed for everyone.
• Awards mutate — appl_id is the key. A supplement revises the amount, a no-cost extension moves the end date, an abstract lands late. Keying the fingerprint on appl_id (not core_project_num) keeps each award year distinct and makes those revisions first-class changed events.
• Windowed on award_notice_date. The delta cursor is the award-notice date; the high-water-mark advances only after a clean, untruncated pass. RePORTER exposes no reliable "last modified" field, so mutation detection is best-effort within whatever window is pulled (documented honestly, not oversold).
• Courtesy User-Agent — sent on every request (USER_AGENT const).