USAspending.gov New Award Monitor

Monitor new federal contract and grant awards from USAspending.gov (U.S. Treasury / DATA Act) in a single run. Give it award types, an awarding agency, and/or NAICS / PSC / recipient / amount filters; it returns one normalized record per prime award as it lands, with a new-since-last-run mode over the nightly-refreshed FPDS (contracts) + FABS (grants) feeds.

Clean REST/JSON — no browser, no proxy, no login, no API key required. The award-search endpoint is a POST API with JSON bodies. Data source: USAspending.gov (U.S. federal, public domain, CC0 1.0).

Status: scaffold (v0.1, in progress). This Actor is being built in slices; the runtime logic (src/usaspending.js, src/filters.js, src/main.js) is landing incrementally. This README documents the intended product surface. See CHANGELOG.md for what's implemented so far.

---

What it does

For each run it queries the USAspending POST /api/v2/search/spending_by_award/ endpoint for the award types you select, over a time window (by new_awards_only, action_date, last_modified_date, or date_signed), applies your filters, pages until page_metadata.hasNext=false, dedupes on Award ID / generated_internal_id, and pushes one dataset item per award.

• New awards (default): with dateType = new_awards_only, only awards first created in the window — every agency, in one pass.
• POST-barrier moat: federal spending is enormous, deeply nested, and gated behind POST bodies with award-type-specific schemas, which structurally deters GET-scraping farms. Freshness (nightly reload) + breadth (every agency) + the POST barrier is the edge.
• New-award monitor: monitorNewOnly persists the set of already-reported award IDs (in the Actor's key-value store) and, on the next scheduled run, returns only awards not seen before.
• Filters: by awardTypeCodes (contracts A/B/C/D, grants 02–05, direct payments, loans), agencies, naicsCodes, pscCodes, recipients, and minAmount.

Inputs

Input	Type	Notes
awardTypeCodes	string[]	A/B/C/D contracts, 02–05 grants, 06/10 direct payments, 07/08 loans. Empty = A,B,C,D
dateType	string	new_awards_only (default), action_date, last_modified_date, date_signed
since	string	YYYY-MM-DD window start. Empty = recent trailing window
until	string	YYYY-MM-DD window end. Empty = today
agencies	string[]	Awarding agency names. Empty = all
naicsCodes	string[]	NAICS industry codes (contracts). Empty = all
pscCodes	string[]	Product/Service Codes (contracts). Empty = all
recipients	string[]	Recipient (awardee) names. Empty = all
minAmount	integer	Minimum Award Amount (0 = no minimum)
monitorNewOnly	boolean	Return only award IDs not seen in a previous run
fields	string[]	Override the requested/kept output fields (empty = sensible default set)
maxResults	integer	Cap total awards returned (0 = no cap)
proxyConfiguration	object	Optional; the API is open and needs no proxy. Default: none

Output — one record per award

{
  "award_id": "CONT_AWD_W912DR26C0001_9700_-NONE-_-NONE-",
  "generated_internal_id": "CONT_AWD_W912DR26C0001_9700_-NONE-_-NONE-",
  "recipient_name": "Example Engineering LLC",
  "award_amount": 4250000.0,
  "award_type": "D",
  "awarding_agency": "Department of Defense",
  "awarding_sub_agency": "Department of the Army",
  "start_date": "2026-07-08",
  "end_date": "2029-07-07",
  "last_modified_date": "2026-07-09",
  "isNew": true,
  "fetchedAt": "2026-07-10T14:00:00.000Z"
}

award_id is USAspending's display Award ID; generated_internal_id is the stable dedupe/detail key (feeds GET /awards/{award_id}/). Amounts are numeric USD; date fields are YYYY-MM-DD (null when absent). isNew is true when an award ID was not seen in a previous run (only meaningful with monitorNewOnly). The exact kept-field set depends on fields and the award families in the run (contracts vs grants expose different selectable fields).

Control records (not charged)

Two non-award records may be pushed to signal run state. Neither triggers an award-returned charge:

Record	When	Shape
_noData	The API returned no awards for the requested filters/window	{ "_noData": true, "filters": {...}, "message": "...", "fetchedAt": "..." }
_error	The fetch failed after retries, or normalization threw	{ "_error": true, "filters": {...}, "message": "...", "fetchedAt": "..." }

_noData keeps a zero-result run green and auditable rather than pushing a silent empty dataset.

Pricing (pay-per-event)

One award-returned event is charged per award record pushed to the dataset. Cost scales with results, not runtime. Use awardTypeCodes / agencies / minAmount / maxResults / monitorNewOnly to keep spend proportional to signal. (Live price shown on the Store page; see docs/PRICING.md.)

Data source & attribution

USAspending.gov's code and data are released under a Creative Commons CC0 1.0 Universal dedication and the underlying federal spending data is public domain (17 U.S.C. §105) — free to copy, modify and redistribute, including commercially, without asking permission. No key and no attribution are required; we credit the U.S. Treasury / USAspending.gov as a courtesy. Full compliance record: COMPLIANCE.md (lands in a later slice).

USAspending relays agency-reported data; awards may be corrected, re-reported, or lag the agencies' own systems, and prime-vs-sub-award distinctions apply. This Actor relays the data as published; it does not certify accuracy.

Maintenance notes

• Award-type-dependent schema — award_type_codes and the selectable fields list differ per award family and shift across API versions; the normalizer keeps the common fields and is defensive.
• Nightly reload windows — FPDS/FABS reload nightly, so a monitoring schedule should overlap its time window run-to-run; last_modified_date mode catches re-reported awards.
• Pagination — limit is capped (100) and page is bounded; page until hasNext=false, dedupe on award ID.
• Prime vs sub-award — this Actor monitors prime awards; sub-awards are a separate endpoint.
• Fiscal-year bulk reloads churn last_modified_date, which can inflate last_modified_date-mode windows near FY boundaries.