USAspending Contract Modification Transaction Ledger

Export every currently published transaction for the federal contract awards you name, straight from the official USAspending API, up to 5,000 transactions per award. Zero-dollar modifications, deobligations (negative amounts) and the base award action are all kept, one row per transaction, with signed amounts as exact two-decimal strings. Optionally keep a baseline in your own account and, on later runs, receive only first-seen transactions and corrected versions of earlier ones, with the previous values attached.

What it does

For each award ID (up to 20 per run) the actor makes four requests to api.usaspending.gov: the award detail (to prove the award exists and is a contract of type A, B, C or D), the transaction count, one transaction list of up to 5,000 rows, and the count again. If the two counts and the returned rows agree, every transaction is delivered, sorted by action date and then transaction ID. Anything that does not agree is reported in the free SUMMARY record instead of being delivered as if it were complete.

• Not unlimited history. Awards with more than 5,000 current transactions are reported as history_limit_exceeded and get no rows. Later pages are never fetched, because USAspending's paging is not a stable snapshot.
• Current published data only. USAspending publishes with a delay that varies; there is no freshness guarantee, and the source keeps no history of earlier versions. Corrections are found by comparing full rescans with your own saved baseline, from the first run of a watch onward.
• A 404 for an award is award_not_found, never an empty ledger. A missing transaction is never reported as deleted.

Input

Field	Meaning
awardIds	1-20 generated contract award IDs starting with CONT_AWD_, as in the award page URL, e.g. CONT_AWD_DENA0003525_8900_-NONE-_-NONE-. Numeric IDs, bare PIIDs, URLs, IDVs, grants and loans are rejected.
watchName	Empty for a one-off export (every run delivers and bills every transaction again). A name keeps a baseline in a named key-value store usaspending-ledger-v1-… in your account; later runs deliver only first-seen and corrected transactions.
maxRows	Most rows stored per run, 1-5,000 (default 1,000). With a named watch, continue rows past it using SUMMARY.resumeInput. For stateless exports set it large enough for the whole result; capped reruns re-deliver and re-bill the first rows.
requestIntervalMs	Idle time after each request, 1,200-10,000 ms (default 1,200).

Run one watch at a time: a second run of the same watch while one is active stops with watch_overlap. A watch holds at most 20,000 transactions, 100 awards and 16 MiB of saved state, one snapshot of at most 8 MiB per award, and it keeps room to rewrite its largest award snapshot, so the usable space is 16 MiB minus that snapshot (and a few hundred bytes for its bookkeeping). It never drops old transactions to make room. A full watch still delivers corrections that fit and reports the changes that do not as state_limit ("The watch is full"). When later receipt writes might have freed capacity, the refused award stays pending for recheck on the next named watch run. A refusal with no later receipt writes is excluded from pending; use a new watch name if it stays full.

Output

One dataset row per delivered transaction version: award_id, transaction_id, action_date (date only), action_type and description, modification_number (text, leading zeros kept), description, federal_action_obligation (signed USD of this action, not the award total), the two other source money fields, event_kind (first_seen_transaction or corrected_transaction), content_hash, previous_content_hash and previous_values for corrections, observed_at (when this actor read it, not when it was published), a ledger_key to upsert on, and source with the exact request and the raw response's SHA-256. The base action has null action type fields, as published.

The free SUMMARY record in the default key-value store reports per award: status, both counts, coverage, rows stored, unchanged count, warnings and any error (with HTTP status and Retry-After). pendingAwardIds and resumeInput describe unfinished work after a cap. Continuation requires a named watch. Without one, pendingAwardIds is diagnostic and resumeInput is null: every new run starts without a baseline and re-delivers and re-bills the first rows. A stateless export needs maxRows large enough for the whole result across all input awards. If the 5,000-row run maximum cannot cover them, split the award list into smaller runs. Other time, request, response and spending limits still apply.

Pricing

Pay per event: $0.003 per stored transaction version (first-seen or corrected) plus $0.00005 per run start. Errors, empty checks, unchanged scans and SUMMARY are free; a quiet watch run costs only the start event. The example award's 314-transaction backfill is $0.94205. A stateless run bills every row again each time.

Limits

20 awards, 80 source requests and about 180 seconds of work per run; 20 seconds per request; 4 MiB per response and 32 MiB per run. A 403, 429, challenge page or redirect stops all requests for the rest of the run, and a 429 is not retried; the SUMMARY says when to try again. No proxy, browser, cookies or login is ever used.

Source and data

Data comes from the public USAspending API run by the U.S. Treasury; no key or account is needed. Rows contain published contract action data only; descriptions may contain names as the government published them. You are the controller of the data you export. An award's presence in USAspending does not mean it is active or a sales lead.