nih_reporter_search_projects
Search NIH RePORTER research-grant projects by state, organization, and fiscal year, with pagination. Returns award amounts, PIs, and UEI identifiers for joining to federal spending data.
Instructions
Search awarded NIH RePORTER research-grant projects (keyless; api.reporter.nih.gov v2, POST/JSON), joinable to SAM/USAspending via primary_uei. LIVE-CONFIRMED-narrowing criteria ONLY, AND-combined: orgStates (UPPERCASE 2-letter USPS — lowercase/unknown code silently returns zeros), orgNames (≤512 chars each, ≤20 names), fiscalYears (int array, 1985..currentYear+1, ≤20), limit (1..500), offset (0..14,999). Returns { projects:[{ projectNum, projectTitle, fiscalYear, awardAmount, organization:{name, state, primaryUei, primaryDuns, ueis, duns}, principalInvestigators, contactPiName, fundingIc }] } + honest _meta. HONESTY: records are RESEARCH GRANTS, NOT procurement contracts — primaryUei joins SAM/USAspending but the award nature differs (disclosed in every _meta.notes). totalAvailable = EXACT meta.total (NEVER the page size, NEVER a lower bound). NIH caps keyless retrieval at the first 15,000 records (offset 0..14,999); offset ≥ 15,000 → invalid_input; past the window the count stays exact while records are UNREACHABLE (disclosed in a note). An unscoped query returns the first page + exact total + narrow-your-criteria note. agencyIcCodes is NOT a filter (NIH silently drops it — would be a false 'applied'). awardAmount is number|null (genuine $0 is 0, absent is null). Genuine total:0 → complete:true/total:0; outage/5xx THROWS; 400 (bad offset/limit/type) → invalid_input; 200 not {meta,results} or non-numeric meta.total → schema_drift.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Projects per page (upstream hard cap 500), 1..500, default 50. | |
| offset | No | 0-based offset into the result set. HARD-CAPPED at 14,999: NIH caps keyless retrieval at the first 15,000 records (offset 0..14,999), so offset ≥ 15,000 is refused (invalid_input) — narrow criteria to reach records beyond the window. The count (totalAvailable) stays EXACT past the window. | |
| orgNames | No | Recipient-organization name filter values (each ≤512 chars, max 20). LIVE-CONFIRMED to narrow. e.g. ['MASSACHUSETTS INSTITUTE OF TECHNOLOGY']. A value matching no org returns a genuine total:0. | |
| orgStates | No | Recipient-organization US state/territory 2-letter USPS codes (UPPERCASE — the enum is the SSRF value guard + the silent-zero guard: a lowercase 'ca' or an unknown 'ZZ' silently returns zeros, so a typo is an invalid_input, never read as 'no NIH funding'). LIVE-CONFIRMED to narrow. e.g. ['CA','MA']. Max 20. | |
| fiscalYears | No | NIH fiscal years to include (int array, 1985..2027, max 20). LIVE-CONFIRMED to narrow. e.g. [2023,2024]. |