USAspending.gov Scraper (Federal Contracts, Grants, Loans)

Search USAspending.gov — the US Treasury's official record of every federal award: contracts, grants, loans, direct payments and IDVs. Keyless, no login; US government work is public domain.

• awards — the spending_by_award search. Pick an award group (contracts / grants / loans / direct-payments / IDVs / other) and filter by agency, recipient, keyword, NAICS / PSC / CFDA code, place of performance, amount band, recipient business type, or disaster-relief code. Keyset pagination from the first request — no 50,000-result ceiling.
• award-detail — a list of generated_internal_ids → the full award record each: total obligation & outlay, sub-award count, recipient UEI / parent, executive compensation, CFDA programs, competition & set-aside detail, place & period of performance.

Record type	One per	Carries
SEARCH_SUMMARY	search run	awardGroup, awardTypeCodes, filtersApplied, resultsReturned, pagesFetched
AWARD	award	generatedInternalId, awardId, recipientName, awardAmount / loanValue, awardingAgency, startDate / endDate, naicsCode, pscCode, cfdaNumber, defCodes, usaspendingUrl — plus obligation/outlay, sub-awards, executive comp etc. on award-detail
ERROR	bad input / missing award	_error + _errorDetail

Every AWARD row carries the verbatim API record in raw (drop with slimOutput).

Things this API will mislead you about

Each is measured, and each has a scenario in tests/smoke/usaspending-scraper_traps.sh (10/10 passing).

page-based pagination stops at 50,000 results (page × limit). Past it the API returns HTTP 422 telling you to switch to keyset. This Actor keyset- paginates (last_record_sort_value + last_record_unique_id) from the first request, so it has no ceiling.

award_type_codes must all be from ONE group — a contract code plus a grant code → HTTP 422. The awardGroup input picks a consistent set; only a rawFilters override can break this.

The sort field must also be in the requested fields — handled automatically. And the sort field must be valid for the award group: loans have no Award Amount (use Loan Value). Each group has a sensible default.

fields names differ by award group — contracts expose NAICS / PSC, grants CFDA Number, loans Loan Value / Subsidy Cost. A name that is wrong for the group comes back null, not an error.

time_period is optional — omitting it searches back to FY2008. This Actor defaults to the last 5 years unless you give dates.

A bad generated_internal_id is an honest HTTP 404. A transient HTML 4xx under a request burst (a proxy hiccup, not a validation error) is retried.

Agency names are matched exactly, case included — USAspending answers "department of defense" with 0 awards and no error (the correctly capitalised name returned 322). This Actor looks every awardingAgency / fundingAgency up in USAspending's own agency list first, so any capitalisation, the usual abbreviations (dod, NASA, hhs) and an unambiguous word (commerce, energy) work; an ambiguous word (defense) lists the candidates, and an unknown name stops the run with the list of valid names instead of an empty result. The summary shows the names actually sent (agencyNamesResolved).

"Awards in 2026" includes awards from years ago — the default dateType (action_date) matches any award with activity in the window, and awardAmount is the award's lifetime amount. Use dateType: new_awards_only for awards first signed in the window, and read baseObligationDate (the first obligation, i.e. the signing date) rather than startDate, which is the period of performance and is often backdated.

Many contract descriptions carry an IGF::..::IGF code (an inherently-governmental-function marker) at the start, the end, or as the whole text. description is kept verbatim; igfCode holds the marker and descriptionClean the text without it.

The summary gives the total — matchingAwards is USAspending's own count for the same filters, next to resultsReturned. If a request fails after some pages, the rows already read are kept and the summary says stoppedBecause: error_after_partial_results.

Notes on cost

awards: one request per 100 results. award-detail: one request per id. No proxy needed.