# USAspending Awards - Contracts, Grants, Loans (`knotty_mistveil/usaspending-federal-awards`) Actor

Federal contracts, IDVs, grants and loans from the official USAspending.gov API v2: recipient, UEI, amount, outlays, NAICS, PSC, agency, place of performance.

- **URL**: https://apify.com/knotty\_mistveil/usaspending-federal-awards.md
- **Developed by:** [Jason](https://apify.com/knotty_mistveil) (community)
- **Categories:** Business, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 award returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## USAspending Awards - Contracts, Grants, Loans

Pulls US federal awards straight from **USAspending.gov**, the official Treasury site for federal spending data, through its public API v2 (`/api/v2/search/spending_by_award/`). No API key, no browser automation, no login. You get one flat JSON record per award - contract, IDV, grant, cooperative agreement, loan or direct payment - with the recipient's name, UEI and address, the total award amount and outlays to date, the awarding and funding agency, the NAICS and PSC codes (contracts) or CFDA programme (assistance), the place of performance, and a link to the award's page on usaspending.gov. Filter by date window, award family, keyword, NAICS, PSC, recipient, awarding agency, state and minimum amount. Federal spending is high volume - **roughly 9,000 to 15,000 awards have an action on a normal weekday** - so read [Limits and freshness](#limits-and-freshness) before you size `maxItems`.

### What you get

Every record contains:

| Field | Description |
| --- | --- |
| `id` | `generated_internal_id`, USAspending's own award key, for example `CONT_AWD_140D0421F0658_1406_HHSN316201200125W_7529` or `ASST_NON_UH3NS143065_075`. Stable across runs - use it to de-duplicate and upsert. |
| `source` | Always `usaspending`. |
| `url` | The public award page, `https://www.usaspending.gov/award/<id>`. |
| `awardGroup` | `contracts`, `idvs`, `grants`, `loans`, `direct-payments` or `other`. |
| `awardId` | PIID for contracts and IDVs, FAIN for assistance awards. |
| `awardType` | `DEFINITIVE CONTRACT`, `DELIVERY ORDER`, `INDEFINITE DELIVERY / INDEFINITE QUANTITY`, `PROJECT GRANT (B)`, `COOPERATIVE AGREEMENT (B)`, `DIRECT LOAN (E)`, `GUARANTEED/INSURED LOAN (F)`, ... Populated for every family, so you can tell a delivery order from a definitive contract and a direct loan from a guaranteed one. |
| `recipientName`, `recipientId`, `recipientUei` | Recipient name, USAspending recipient hash and the 12-character Unique Entity Identifier. |
| `recipientAddress`, `recipientCity`, `recipientState`, `recipientStateName`, `recipientZip`, `recipientCountry`, `recipientCongressionalDistrict` | The recipient's registered business address. |
| `amount` | Total award amount in USD over the award's whole life (`Award Amount`, or `Loan Value` for loans) - **not** the amount obligated inside your date window. |
| `totalOutlays` | Money actually paid out so far, USD. `null` when the source publishes none. |
| `subsidyCost` | Loans only: the government's subsidy cost, USD (often negative). |
| `description` | The award description as filed, upper-case, up to several thousand characters. |
| `startDate`, `endDate` | Period of performance. For loans `startDate` is the issue date; IDVs have no end date. |
| `lastDateToOrder` | IDVs only: the last date orders may be placed against the vehicle. |
| `baseObligationDate` | Date of the award's base transaction. |
| `lastModified` | When USAspending last modified the record, ISO 8601 without an offset (the API publishes no timezone). |
| `awardingAgency`, `awardingAgencyCode`, `awardingSubAgency` | Who awarded it. |
| `fundingAgency`, `fundingSubAgency` | Who paid for it, when different. |
| `naicsCode`, `naicsDescription`, `pscCode`, `pscDescription` | Industry and product/service classification. Contracts and IDVs only; `null` on assistance awards. |
| `cfdaNumber`, `cfdaProgramTitle`, `assistanceListings`, `saiNumber` | Assistance Listing (CFDA) programme for grants, loans and direct payments; `assistanceListings` is the full array when an award draws on several. `null`/`[]` on contracts. |
| `placeOfPerformanceState`, `placeOfPerformanceStateName`, `placeOfPerformanceCity`, `placeOfPerformanceCounty`, `placeOfPerformanceZip`, `placeOfPerformanceCountry`, `placeOfPerformanceCongressionalDistrict` | Where the work is done. |
| `defCodes` | Disaster Emergency Fund Codes attached to the award (`Q`, `AAA`, `L`, ...); `[]` when none. |
| `covidObligations`, `covidOutlays`, `infrastructureObligations`, `infrastructureOutlays` | COVID-19 supplemental and IIJA (infrastructure) money on the award, USD. |
| `fetchedAt` | ISO timestamp of the run that produced the record. |

The dataset has three views: **Overview** (award, recipient, amount, agency, NAICS/PSC, dates, link), **Recipients** (name, UEI, full address, district - the lead-generation view) and **Grants and loans** (CFDA programme, subsidy cost, period).

### Input

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `awardGroup` | string | `contracts` | `contracts` (A/B/C/D), `idvs` (IDV\_A..IDV\_E), `grants` (02/03/04/05), `loans` (07/08), `direct-payments` (06/10), `other` (09/11), or `all`. USAspending allows only one family per query, so `all` runs one query per family and merges them into a single sorted stream. |
| `daysBack` | integer | `30` | Look-back window in days ending today. Ignored when `dateFrom`/`dateTo` are set. |
| `dateFrom` | string | - | Start of the window, `YYYY-MM-DD`. Not earlier than `2007-10-01`; the run stops with a clear message if it is. |
| `dateTo` | string | today | End of the window, `YYYY-MM-DD`. |
| `dateType` | string | `action_date` | Which award date the window matches: `action_date` (latest transaction on the award), `new_awards_only` (base transaction inside the window - genuinely new awards), `date_signed` (same anchor as `new_awards_only`), `last_modified_date` (record touched by USAspending - the widest). |
| `keywords` | string\[] | none | Sent to the USAspending keyword filter, which searches the award description, recipient name, award ID **and** the NAICS/PSC descriptions. Terms are ORed. |
| `naicsCodes` | string\[] | all | NAICS codes or prefixes, 2 to 6 digits, ORed. `5415` = computer systems design, `54` = professional/scientific/technical, `23` = construction, `3364` = aerospace, `62` = health care. Contracts and IDVs only. |
| `pscCodes` | string\[] | all | Product and Service Codes or prefixes, 1 to 4 characters, ORed. `D` = IT and telecom services, `R` = professional support, `Y` = construction, `70` = general-purpose IT equipment. Contracts and IDVs only. |
| `recipientSearch` | string\[] | all | Recipient names or UEI/DUNS identifiers, ORed. Substrings work: `"Lockheed"` matches every Lockheed entity. |
| `agencies` | string\[] | all | Top-tier awarding agency names as USAspending spells them (`"Department of Defense"`, `"General Services Administration"`). An unambiguous partial name is accepted; an unknown name **stops the run** rather than returning zero rows. |
| `states` | string\[] | all | Two-letter place-of-performance state or territory codes (`VA`, `TX`, `PR`). |
| `minAmount` | integer | `0` | Keep only awards worth at least this much (the total award amount). |
| `sortBy` | string | `amount` | `amount` (biggest first - right when `maxItems` is smaller than the match count) or `lastModified` (most recently updated first - right for a monitoring feed). |
| `order` | string | `desc` | `desc` or `asc`. |
| `maxItems` | integer | `500` | Stop after this many awards. You are charged per award, so this is also the cost cap. See [Limits and freshness](#limits-and-freshness) - the default is a sample of a very large feed, not a complete window. |

Example - IT services contracts awarded in Virginia in the last fortnight, worth at least US$1m:

```json
{
  "awardGroup": "contracts",
  "daysBack": 14,
  "naicsCodes": ["5415"],
  "states": ["VA"],
  "minAmount": 1000000,
  "maxItems": 1000
}
```

Example - a daily monitoring feed of genuinely new NIH grants, newest first:

```json
{
  "awardGroup": "grants",
  "daysBack": 10,
  "dateType": "new_awards_only",
  "agencies": ["Department of Health and Human Services"],
  "sortBy": "lastModified",
  "maxItems": 2000
}
```

Bad input fails fast: a malformed date, a `dateFrom` before 2007-10-01, a NAICS code that is not 2-6 digits, a PSC longer than 4 characters, a state that is not two letters, a negative `minAmount`, an unknown `awardGroup`/`dateType`/`sortBy`, or an awarding agency name that does not exist all stop the run with the validation message as its status - the agency check before any award request is made.

### Output example

A real contract record from a live run on 2026-09-08 (`{"awardGroup":"contracts","daysBack":7,"keywords":["cybersecurity"],"maxItems":3}`), unedited:

```json
{
  "id": "CONT_AWD_140D0421F0658_1406_HHSN316201200125W_7529",
  "source": "usaspending",
  "url": "https://www.usaspending.gov/award/CONT_AWD_140D0421F0658_1406_HHSN316201200125W_7529",
  "awardGroup": "contracts",
  "awardId": "140D0421F0658",
  "awardType": "DELIVERY ORDER",
  "recipientName": "CUSTOMER VALUE PARTNERS, LLC",
  "recipientId": "8a2c800a-0d04-3aaf-816b-5aeb9d1b3726-C",
  "recipientUei": "L6R3M86AFBB5",
  "recipientCity": "FAIRFAX",
  "recipientState": "VA",
  "recipientStateName": "Virginia",
  "recipientZip": "22030",
  "recipientCountry": "USA",
  "recipientAddress": "3701 PENDER DR",
  "recipientCongressionalDistrict": "98",
  "amount": 31451071.79,
  "totalOutlays": 28779613.27,
  "subsidyCost": null,
  "description": "ENTERPRISE CYBERSECURITY SUPPORT SERVICES (ECSS)",
  "startDate": "2021-09-21",
  "endDate": "2026-11-20",
  "lastDateToOrder": null,
  "baseObligationDate": "2021-09-20",
  "lastModified": "2026-09-04T13:48:29",
  "awardingAgency": "Department of the Interior",
  "awardingAgencyCode": "014",
  "awardingSubAgency": "Departmental Offices",
  "fundingAgency": "Department of Health and Human Services",
  "fundingSubAgency": "National Institutes of Health",
  "naicsCode": "541512",
  "naicsDescription": "COMPUTER SYSTEMS DESIGN SERVICES",
  "pscCode": "DJ01",
  "pscDescription": "IT AND TELECOM - SECURITY AND COMPLIANCE SUPPORT SERVICES (LABOR)",
  "cfdaNumber": null,
  "cfdaProgramTitle": null,
  "assistanceListings": [],
  "saiNumber": null,
  "placeOfPerformanceState": "MD",
  "placeOfPerformanceStateName": "Maryland",
  "placeOfPerformanceCity": "BETHESDA",
  "placeOfPerformanceCounty": "MONTGOMERY",
  "placeOfPerformanceZip": "20892",
  "placeOfPerformanceCountry": "USA",
  "placeOfPerformanceCongressionalDistrict": "08",
  "defCodes": ["Q"],
  "covidObligations": 0,
  "covidOutlays": 0,
  "infrastructureObligations": 0,
  "infrastructureOutlays": 0,
  "fetchedAt": "2026-09-08T02:19:59.606Z"
}
```

A grant from the same day (`{"awardGroup":"grants","daysBack":7,"states":["CA"],"sortBy":"lastModified"}`), with the fields shared with the contract above omitted and the description trimmed:

```json
{
  "id": "ASST_NON_UH3NS143065_075",
  "url": "https://www.usaspending.gov/award/ASST_NON_UH3NS143065_075",
  "awardGroup": "grants",
  "awardId": "UH3NS143065",
  "awardType": "COOPERATIVE AGREEMENT (B)",
  "recipientName": "UNIVERSITY OF SOUTHERN CALIFORNIA",
  "recipientUei": "G88KLJR3KYT5",
  "recipientAddress": "3720 S FLOWER ST FL 3",
  "recipientCity": "LOS ANGELES",
  "recipientState": "CA",
  "amount": 772119,
  "description": "DEVELOPMENT OF ANGIOTENSIN AT2 INHIBITORS FOR NEUROPATHIC PAIN RELIEF - PROJECT SUMMARY ...",
  "startDate": "2025-06-01",
  "endDate": "2029-05-31",
  "baseObligationDate": "2026-09-01",
  "lastModified": "2026-09-04T22:02:54",
  "awardingAgency": "Department of Health and Human Services",
  "awardingSubAgency": "National Institutes of Health",
  "naicsCode": null,
  "pscCode": null,
  "cfdaNumber": "93.853",
  "cfdaProgramTitle": "EXTRAMURAL RESEARCH PROGRAMS IN THE NEUROSCIENCES AND NEUROLOGICAL DISORDERS",
  "saiNumber": "SAI UNAVAILABLE",
  "placeOfPerformanceCity": "LOS ANGELES",
  "placeOfPerformanceState": "CA",
  "defCodes": []
}
```

And a loan (`{"awardGroup":"loans","daysBack":60,"minAmount":1000000,"maxItems":2}`), same trimming - `amount` carries the face value from `Loan Value`, `awardType` separates direct loans from guaranteed ones, and `totalOutlays`/`endDate` are `null` because the source publishes neither for this family:

```json
{
  "id": "ASST_NON_P268K134897_091",
  "url": "https://www.usaspending.gov/award/ASST_NON_P268K134897_091",
  "awardGroup": "loans",
  "awardId": "P268K134897",
  "awardType": "DIRECT LOAN (E)",
  "recipientName": "CAPELLA EDUCATION COMPANY",
  "recipientUei": "PBSBCK9D8BF7",
  "recipientAddress": "CAPELLA TOWER, 9TH FLOOR",
  "recipientCity": "MINNEAPOLIS",
  "recipientState": "MN",
  "amount": 4829148534,
  "totalOutlays": null,
  "subsidyCost": 0,
  "description": "DL BASE RECORD 2012-2013",
  "startDate": "2026-08-20",
  "endDate": null,
  "baseObligationDate": "2012-03-26",
  "lastModified": "2026-09-02T20:10:08",
  "awardingAgency": "Department of Education",
  "awardingSubAgency": "Department of Education",
  "cfdaNumber": "84.268",
  "cfdaProgramTitle": "FEDERAL DIRECT STUDENT LOANS",
  "placeOfPerformanceCity": "MINNEAPOLIS",
  "placeOfPerformanceState": "MN",
  "defCodes": []
}
```

The run also writes a `SUMMARY` record to the key-value store: awards pushed, pages read per award group, **how many awards actually matched your filters on USAspending**, the date window and date type, and USAspending's own data load date. A real one, from `{"awardGroup":"contracts","dateFrom":"2026-08-25","dateTo":"2026-09-08","naicsCodes":["5415"],"maxItems":500}` on 2026-09-08:

```json
{
  "pushed": 500,
  "limitReached": true,
  "scanned": 500,
  "filteredOut": { "minAmount": 0, "duplicate": 0, "missingId": 0 },
  "perGroup": { "contracts": { "pages": 5, "scanned": 500, "pushed": 500 } },
  "availableOnSource": { "contracts": 2754 },
  "availableOnSourceIgnoresMinAmountFor": [],
  "dataLastUpdated": "09/07/2026",
  "dateFrom": "2026-08-25",
  "dateTo": "2026-09-08",
  "dateType": "action_date",
  "awardGroups": ["contracts"],
  "sortBy": "amount",
  "order": "desc"
}
```

`availableOnSource` counts **only the award families this run queried, with the same award type codes**, so it is directly comparable with `pushed`: the same input with `maxItems: 5000` delivered exactly 2,754 records with 2,754 distinct `id`s. `availableOnSourceIgnoresMinAmountFor` names any family whose figure is an upper bound rather than an exact match - only `loans` can appear there, and only when you set `minAmount` (see [Limits and freshness](#limits-and-freshness)).

### Pricing

Pay per result: **US$0.003 per award delivered** (US$3 per 1,000 awards). You are charged only for records pushed to the dataset; a run that returns nothing costs nothing. Runs on the Apify free plan are limited by the platform's free-tier usage allowance.

### Data source and licence

- Endpoint: `POST https://api.usaspending.gov/api/v2/search/spending_by_award/`, published by the **US Department of the Treasury, Bureau of the Fiscal Service** as the official DATA Act site. API index: <https://api.usaspending.gov/docs/endpoints>. Request contract: <https://github.com/fedspendingtransparency/usaspending-api/blob/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_award.md>.
- The Actor also calls `POST /api/v2/search/spending_by_award_count/` once per run to report how many awards matched (twice when you combine `minAmount` with `awardGroup: "loans"` or `"all"`, because the loan count has to be taken without the amount filter), `GET /api/v2/awards/last_updated/` (data load date) and `GET /api/v2/references/toptier_agencies/` (only when you set `agencies`, to validate the names).
- **Licence:** the data is a work of the United States Government and is in the public domain under 17 U.S.C. § 105; USAspending publishes it under the DATA Act with no registration, key or usage terms. The USAspending API itself is released under **CC0 1.0 Universal** (<https://github.com/fedspendingtransparency/usaspending-api/blob/master/LICENSE>, read 8 September 2026), which permits commercial reuse without attribution. Crediting "USAspending.gov" and linking the award page is still good practice, and the source values are reproduced here unchanged so buyers can check them.
- **Personal data.** Federal award records name the recipient organisation and give its registered business address (`recipientName`, `recipientAddress`, `recipientCity`, `recipientZip`). Most recipients are companies, universities and governments, but sole proprietors and individual grantees also receive federal awards, and for those the "business" address can be a home address. USAspending itself redacts individuals where the law requires it - such records arrive with `recipientName` set to `REDACTED DUE TO PII` and an empty address, and the Actor passes that through unchanged rather than trying to fill it in. No email addresses or telephone numbers are published by this endpoint. Publication is lawful under the DATA Act; how you use the names and addresses afterwards - marketing in particular - is your responsibility under the applicable rules (CAN-SPAM, TCPA, state privacy laws, and GDPR if you process them in the EU or UK).

### Limits and freshness

All figures below were measured against the live API on **8 September 2026**.

- **Volumes.** Counted with `spending_by_award_count` on `action_date`, one day at a time: 26 Aug (Wed) 9,242 awards, 27 Aug (Thu) 10,637, 28 Aug (Fri) 9,390, 29 Aug (Sat) 1,759, 30 Aug (Sun) 742, 31 Aug (Mon) 12,912, 1 Sep (Tue) 9,194, 2 Sep (Wed) 15,437, 3 Sep (Thu) 9,530 - so **about 9,000 to 15,000 awards per weekday** and well under 2,000 at weekends. Over a whole week (1-8 Sep) 36,561 awards had an action: 30,330 contracts, 4,357 grants, 1,811 IDVs, 61 direct payments, 2 loans. Over 30 days (9 Aug - 8 Sep) 232,372: 155,643 contracts, 42,653 grants, 22,032 direct payments, 7,891 IDVs, 2,335 other, 1,818 loans. All figures are counted with the same award type codes the Actor queries (see the next bullet).
- **Reachable totals, not category totals.** USAspending's count endpoint, asked without `award_type_codes`, buckets awards by *category*, and that is a wider set than any award-type query can return - the search endpoint itself refuses to run without `award_type_codes`. The 30-day window above answers 237,506 category-wide against the 232,372 the codes can reach (the gap is 2,805 grants, 2,290 loans and 39 direct payments); a 60-day place-of-performance WY window answers grants 511 / loans 98 category-wide against 412 / 60 by code. The Actor counts by code, so `SUMMARY.availableOnSource` never promises rows it cannot deliver: that WY window reported 1,752 available and delivered 1,752 with 1,752 distinct ids.
- **Size `maxItems` to the window - the default is a sample, not an archive.** `maxItems` counts records delivered, and the stream is ordered by `sortBy`, so an unfiltered run returns the top N by award amount (or the N most recently modified) and stops. Truncation is never silent, and does not depend on the count endpoint being reachable or exact: any run that stops at the limit logs `maxItems (N) was reached: more awards match these filters than this run returned` and sets `SUMMARY.limitReached`, and when the counts are available the run also logs `N awards match these filters but maxItems is M` and records both figures in `SUMMARY`. Narrow with `naicsCodes`, `pscCodes`, `keywords`, `agencies`, `states` or `minAmount` before raising `maxItems`.
- **Freshness and lag.** `GET /api/v2/awards/last_updated/` reported `09/07/2026` on 8 September, and every run copies that into `SUMMARY.dataLastUpdated`. The action-date counts show the practical lag: the four most recent days were still filling in (4 Sep 2,300, 5 Sep 93, 6 Sep 3, 7 Sep 2, 8 Sep 2) against 1,759 for the equivalent Saturday a week earlier. **Treat the newest 3 to 4 days as incomplete**; a daily schedule with `daysBack: 7` or more re-reads that tail as it fills.
- **One record per award, not per transaction.** An award that is modified appears again in every later window that contains one of its actions, with the same `id`. `amount` is the award's whole-life total, not the money obligated inside your window, so summing `amount` over a window over-counts. Use `id` to upsert, and USAspending's own transaction endpoints if you need per-transaction obligations.
- **Rate limits and run time.** None is documented and none was observed: 20 back-to-back page requests all returned HTTP 200 in about 1.0 s each with no `429` and no rate-limit headers. Pages are 100 records (the API's maximum - it rejects `limit: 500` with `Field 'limit' value '500' is above max '100'`) and are spaced 200 ms apart out of politeness. Measured throughput: **500 awards in 7 seconds, 2,754 awards in 36 seconds** (28 pages), roughly 13 seconds per 1,000 awards. `fetchWithRetry` still retries `429` and `5xx` with exponential back-off and honours `Retry-After`.
- **Deep paging works, but the API's own `hasNext` flag does not.** `page_metadata.hasNext` turns `false` at page 100 (10,000 records) even when the result set is far larger. Verified on a 30,330-record window: pages 101 to 303 each returned 100 distinct, correctly sorted records and page 304 returned the final 30. The Actor therefore pages until a page comes back short, and a 2,754-record filtered run delivered exactly the 2,754 the count endpoint promised, with no duplicates.
- **One award family per query.** The search endpoint rejects mixed `award_type_codes` (`'award_type_codes' must only contain types from one group.`), so `awardGroup: "all"` issues one paged query per family and merges the six streams on the sort key. That costs one extra first-page request per family. The count endpoint is the exception: it does accept codes from several families in one request, which is why a run of any size still needs only one count call.
- **Field coverage differs by family.** Contracts and IDVs carry `NAICS`/`PSC` and no CFDA; grants, loans and direct payments carry CFDA and no NAICS/PSC; loans report `Loan Value` and `Subsidy Cost` instead of `Award Amount` and `Total Outlays` (the Actor maps `Loan Value` onto `amount`); IDVs have `lastDateToOrder` instead of `endDate`. Nothing is invented - a field the source does not publish for that family is `null`.
- **`minAmount` on loans is applied locally, and its count is an upper bound.** USAspending's `award_amounts` filter reads the award's obligation rather than its face value, so on loans it drops the wrong rows: over 10 Jul - 8 Sep the largest loan is a `Loan Value` of $4,829,148,534, yet `lower_bound: 1000` already excludes it and cuts the loan count from 72,036 to 1,992. The Actor therefore never sends that filter for loans - it filters on `amount` itself after fetching, so a `minAmount` run on loans really does return every loan at or above your figure, biggest first. The cost is that USAspending cannot count them for you: `SUMMARY.availableOnSource.loans` then counts every loan in the window, `SUMMARY.availableOnSourceIgnoresMinAmountFor` lists `loans` to say so, and the log calls the total an upper bound. For every other family `minAmount` runs server-side and the count is exact.
- **Window edges.** `dateFrom`/`dateTo` are inclusive calendar dates sent to the API unchanged; the API refuses anything before **2007-10-01** and the Actor stops with that message rather than sending it. For older awards use USAspending's bulk download endpoints.
- **This endpoint returns no per-record action date.** The window is applied server-side; each record carries `baseObligationDate` and `lastModified` only.
- **`recipientSearch` with several terms.** The contract documents a one-item limit for `recipient_search_text`, but multiple terms were accepted and ORed correctly in testing (`["Lockheed", "Boeing"]` returned both). If Treasury ever enforces the documented limit, use one term per run.

### Use cases

- **Competitor and incumbent intelligence.** Watch who wins what in your NAICS or PSC codes, at what value, funded by which agency, and when the period of performance ends - `endDate` and `lastDateToOrder` tell you when the re-compete is coming.
- **Lead generation for the federal supply chain.** The Recipients view gives you prime awardees with their UEI, full business address and congressional district, filtered to your state and industry - the buying list for subcontracting, staffing, insurance, financing and compliance services.
- **Grant and funding research.** Track which institutions receive which CFDA programmes, at what value, with `dateType: "new_awards_only"` for genuinely new awards rather than modifications - for research offices, non-profits and consultancies chasing the same programmes.

### Support

Open an issue on the Actor's Issues tab on Apify Store. Replies within 14 days. Bug reports that name the run id and the input used are fixed fastest.

# Actor input Schema

## `awardGroup` (type: `string`):

Which family of federal awards to return. USAspending only allows one family per query, so "All award types" runs one query per family and merges them into a single sorted stream. Contracts = A/B/C/D, IDVs = IDV\_A..IDV\_E, grants = 02/03/04/05, loans = 07/08, direct payments = 06/10, other = 09/11.

## `daysBack` (type: `integer`):

Look-back window in days, ending today. Ignored when Date from / Date to are set. USAspending finishes loading a day's awards about 3 to 4 days later, so a window shorter than a week is always incomplete at its newest edge.

## `dateFrom` (type: `string`):

Start of the window, YYYY-MM-DD (inclusive). Overrides Days back. The award search does not go back beyond 2007-10-01.

## `dateTo` (type: `string`):

End of the window, YYYY-MM-DD (inclusive). Defaults to today.

## `dateType` (type: `string`):

Which award date the window is matched against. Action date = the latest transaction on the award (the default; catches modifications to old awards too). New awards only = the award's base transaction, so you get genuinely new awards. Date signed behaves the same as new awards only. Last modified date = when USAspending last touched the record, which is the widest of the four.

## `keywords` (type: `array`):

Free-text terms sent to the USAspending keyword filter, which searches the award description, recipient name, award ID and the NAICS/PSC descriptions. Terms are ORed. Empty = no keyword filter.

## `naicsCodes` (type: `array`):

NAICS industry codes or prefixes, 2 to 6 digits; an award matches when its NAICS code starts with any of them. 5415 = computer systems design, 54 = professional/scientific/technical services, 23 = construction, 3364 = aerospace, 62 = health care. Contracts and IDVs only - assistance awards carry no NAICS. Empty = all.

## `pscCodes` (type: `array`):

Product and Service Codes or prefixes, 1 to 4 characters; an award matches when its PSC starts with any of them. D = IT and telecom services, R = professional support services, Y = construction, 70 = general purpose IT equipment. Contracts and IDVs only. Empty = all.

## `recipientSearch` (type: `array`):

Recipient names or UEI/DUNS identifiers; awards matching any of them are kept. Substrings work ("Lockheed" matches every Lockheed entity). Empty = all recipients.

## `agencies` (type: `array`):

Top-tier awarding agency names, exactly as USAspending spells them, for example "Department of Defense", "General Services Administration", "Department of Health and Human Services". The full list is at https://api.usaspending.gov/api/v2/references/toptier\_agencies/. An unambiguous partial name is accepted; an unknown name stops the run instead of quietly returning nothing. Empty = all agencies.

## `states` (type: `array`):

Two-letter US state or territory codes for where the work is performed, for example VA, TX, CA, PR. Empty = the whole country and overseas.

## `minAmount` (type: `integer`):

Keep only awards worth at least this much in USD (the total award amount over the award's life, not the amount obligated inside the window). 0 = no minimum. Applied by USAspending for every family except loans, where its amount filter reads the obligation rather than the loan's face value and would drop the largest loans - loans are filtered on the loan value itself while paging, so the run scans more records than it returns and the loan figure in SUMMARY.availableOnSource is an upper bound.

## `sortBy` (type: `string`):

Award amount returns the biggest awards first, which is what you want when maxItems is smaller than the match count. Last modified date returns the most recently updated records first, which is what you want for a daily monitoring feed.

## `order` (type: `string`):

Descending (biggest / newest first) or ascending.

## `maxItems` (type: `integer`):

Stop after this many awards. You are charged per award delivered, so this is also the cost cap. Federal spending is high volume - roughly 9,000 to 15,000 awards have an action on a normal weekday - so anything smaller than the match count keeps only the top N by the sort you chose. The run logs how many awards actually match and writes the figure to the SUMMARY record.

## Actor input object example

```json
{
  "awardGroup": "contracts",
  "daysBack": 30,
  "dateType": "action_date",
  "keywords": [],
  "naicsCodes": [],
  "pscCodes": [],
  "recipientSearch": [],
  "agencies": [],
  "states": [],
  "minAmount": 0,
  "sortBy": "amount",
  "order": "desc",
  "maxItems": 500
}
```

# Actor output Schema

## `results` (type: `string`):

All awards returned by the run, one JSON object each. Append ?format=csv or ?format=xlsx to download a spreadsheet.

## `summary` (type: `string`):

Counts per award group, how many awards matched the filters on USAspending (counted with the same award type codes the run queried, so the figure is comparable with what was delivered), whether the run stopped at maxItems, the date window used and USAspending's data load date, written at the end of the run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "awardGroup": "contracts",
    "daysBack": 30,
    "dateType": "action_date",
    "keywords": [],
    "naicsCodes": [],
    "pscCodes": [],
    "recipientSearch": [],
    "agencies": [],
    "states": [],
    "minAmount": 0,
    "sortBy": "amount",
    "order": "desc",
    "maxItems": 500
};

// Run the Actor and wait for it to finish
const run = await client.actor("knotty_mistveil/usaspending-federal-awards").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "awardGroup": "contracts",
    "daysBack": 30,
    "dateType": "action_date",
    "keywords": [],
    "naicsCodes": [],
    "pscCodes": [],
    "recipientSearch": [],
    "agencies": [],
    "states": [],
    "minAmount": 0,
    "sortBy": "amount",
    "order": "desc",
    "maxItems": 500,
}

# Run the Actor and wait for it to finish
run = client.actor("knotty_mistveil/usaspending-federal-awards").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "awardGroup": "contracts",
  "daysBack": 30,
  "dateType": "action_date",
  "keywords": [],
  "naicsCodes": [],
  "pscCodes": [],
  "recipientSearch": [],
  "agencies": [],
  "states": [],
  "minAmount": 0,
  "sortBy": "amount",
  "order": "desc",
  "maxItems": 500
}' |
apify call knotty_mistveil/usaspending-federal-awards --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,knotty_mistveil/usaspending-federal-awards"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/s9YAfF50cHl3ksI6S/builds/VBMAtrGmF3o1xahK0/openapi.json