# USAspending Awards API — Federal Contract Awards & Grants (`samgov-tools/usaspending-awards`) Actor

Export federal contract awards, IDVs and grants from USAspending.gov to JSON/CSV — no API key or account. Filter by keyword, NAICS, awarding agency, recipient, place-of-performance state and date range. $1 per 1,000 awards, platform usage included.

- **URL**: https://apify.com/samgov-tools/usaspending-awards.md
- **Developed by:** [AgentReady Tools](https://apify.com/samgov-tools) (community)
- **Categories:** Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## USAspending Awards API — Federal Contract Awards & Grants

Export US federal contract awards, IDVs and grants from USAspending.gov to JSON, CSV or Excel — no API key or account. Search by keyword, NAICS, awarding agency, recipient, place-of-performance state and date range, and get flat records with recipient name and UEI, agency and sub-agency, award amount, NAICS/PSC, dates, place of performance and a link to the public award page. Useful for competitor research, incumbent analysis and GovCon lead lists. $1 per 1,000 awards, platform usage included.

Data is public US federal spending data, not procurement opportunities or private contact information. Empty input searches contracts for the last 30 days inclusive, ending today UTC, and stores up to 10 awards. Results are sorted by award amount descending. Optional IDV and grant searches use their own supported field sets.

### For AI agents

Returns flat federal contract, IDV, or grant award records with recipients, USD amounts, agencies, dates, and public source links.

Connect your MCP client to `https://mcp.apify.com?tools=samgov-tools/usaspending-awards`. Example prompt: “Find up to 10 software contract awards with activity in Virginia during the last 30 days and report recipients, amounts, and source links.”

Call with `{}` for up to 10 recent contracts, or start with 1–3 filters such as `{"keywords":"software","state":"VA","maxItems":10}`. Read `recipientName` and `awardAmount` for summaries, `awardId` / `generatedInternalId` for identity, and `usaspendingUrl` for source verification. All items have the same 27 fields; unavailable values are `null`. Results are sorted by amount descending; the default date window matches activity. Set `newAwardsOnly: true` for newly started awards.

REST API (replace `$APIFY_TOKEN` with your token through an environment variable):

```sh
curl --request POST \
  'https://api.apify.com/v2/acts/samgov-tools~usaspending-awards/run-sync-get-dataset-items' \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"keywords":"software","maxItems":10}'
```

JavaScript with `apify-client` installed:

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('samgov-tools/usaspending-awards').call({
  keywords: 'software',
  maxItems: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

Example JSON item (illustrative values, not a verified award):

```json
{
  "awardId": "SPE30018FLGFZ",
  "generatedInternalId": "CONT_AWD_SPE30018FLGFZ_9700_SPE30017D0001_9700",
  "recipientName": "PUBLIC AWARD RECIPIENT",
  "recipientUei": null,
  "awardAmount": 125000.5,
  "awardingAgency": null,
  "awardingAgencyCode": null,
  "awardingSubAgency": null,
  "awardingSubAgencyCode": null,
  "fundingAgency": null,
  "fundingSubAgency": null,
  "contractAwardType": null,
  "awardType": null,
  "naicsCode": "561210",
  "naicsDescription": null,
  "pscCode": null,
  "pscDescription": null,
  "placeOfPerformanceCity": null,
  "placeOfPerformanceState": "VA",
  "placeOfPerformanceCountry": null,
  "placeOfPerformanceZip": null,
  "startDate": null,
  "endDate": null,
  "lastModifiedDate": null,
  "baseObligationDate": null,
  "description": null,
  "usaspendingUrl": "https://www.usaspending.gov/award/CONT_AWD_SPE30018FLGFZ_9700_SPE30017D0001_9700"
}
```

#### Paying agents without an Apify account (x402 / MPP)

An agent without an Apify account can buy a prepaid Apify API token from Apify AGI (`agi.apify.com`) with x402 (USDC on Base or Solana), MPP (Tempo or Solana) or Skyfire, then use it as the Apify API token in this README's REST example (Actor `samgov-tools~usaspending-awards`) or as the bearer token for the Apify MCP server. This Actor uses limited permissions, which prepaid tokens require. Apify's current terms: minimum $1, the balance is a hard spending cap, the token expires 14 days after purchase, unused balance is non-refundable, and the feature is experimental. Check `agi.apify.com` for current terms before paying.

The token pays this Actor's normal pay-per-event prices: `award`: $0.001 per stored award. See [Let your AI agent pay for Actor runs](https://docs.apify.com/agents/payments), [x402](https://docs.apify.com/platform/integrations/x402) and [MPP](https://docs.apify.com/integrations/mpp).

### Pricing

$1 per 1,000 awards ($0.001 each), pay per event (PPE), with platform usage included. The `award` event is charged only for successfully stored awards. Invalid records are skipped without charge. The Actor stops when the event charge limit is reached. Reruns can store and charge for the same awards again; there is no cross-run deduplication.

### Input

| Field | Meaning | Default |
| --- | --- | --- |
| `keywords` | Filter awards by search text; use a string with commas between multiple keywords. Default: omitted, no keyword filter. Use to target a product or service. Example: "software,cloud". | Omitted |
| `naics` | Filter by industry using a string of comma-separated NAICS prefixes, each 2–6 digits. Default: omitted, no NAICS filter. Use for industry-specific searches. Example: "541512,541511". | Omitted |
| `agency` | Filter by the exact official awarding toptier agency name as a string. Default: omitted, all agencies. Use to research a specific federal buyer. Example: "Department of Defense". | Omitted |
| `recipientName` | Search recipient names and identifiers using a text string. Default: omitted, all recipients. Use to research an award recipient or incumbent. Example: "LOCKHEED MARTIN". | Omitted |
| `awardDateFrom` | Set the inclusive window start as YYYY-MM-DD or MM/dd/yyyy, no earlier than 2007-10-01. Default: 29 days before awardDateTo. Use for historical searches. Matches activity unless newAwardsOnly is true. Example: "2026-01-01". | End minus 29 days |
| `awardDateTo` | Set the inclusive window end as YYYY-MM-DD or MM/dd/yyyy, on or after awardDateFrom. Default: today UTC. Use to bound a historical search. Matches activity unless newAwardsOnly is true. Example: "2026-01-31". | Today UTC |
| `newAwardsOnly` | Set a JSON boolean to restrict the date window to award base/start dates using the API new_awards_only date_type. Default: false, which matches award activity and can include older awards with later actions. Use true for new-win lists. Example: true. | false |
| `state` | Filter place of performance using a two-letter US state, territory, or military code; lowercase is accepted. Default: omitted, no location filter. Use to target where work takes place. Example: "VA". | Omitted |
| `awardType` | Choose one string: contracts, idvs (indefinite delivery vehicles), or grants. Default: "contracts". Use to switch the award category; grants omit contract-only NAICS/PSC output values. Example: "grants". | contracts |
| `maxItems` | Limit the number of awards stored using a JSON integer from 1 to 10000. Default: 10. Use a smaller value for previews or a larger value for exports; charge limits may stop earlier. Example: 25. | 10 |
| `pageSize` | Set the USAspending API page size using a JSON integer from 1 to 100. Default: 100. Use a smaller value when smaller API batches are useful; maxItems still caps stored awards. Example: 50. | 100 |

Dates accept `YYYY-MM-DD` or `MM/dd/yyyy`; the API receives ISO dates. Start must be at least 2007-10-01 and no later than end. If only start is supplied, end is today UTC. If only end is supplied, start is 29 days earlier. By default the date range matches award activity, not necessarily the award start date; set `newAwardsOnly` to `true` (recommended for new-win lists) to limit results to awards whose base/start date falls in the window. State codes include DC, PR, VI, GU, AS, MP and AA, AE, AP; lowercase is accepted. Agency names must match the official toptier name.

```json
{"keywords":"software","naics":"541512,541511","agency":"Department of Defense","state":"VA","newAwardsOnly":true,"maxItems":25}
```

### Output fields

Every item includes every field below, with `null` for missing data. NAICS, PSC, and primary place of performance are flattened. Amount is a finite number in USD or null. Records missing both identifiers are rejected.

| Field | Meaning |
| --- | --- |
| `awardId` | Public award identifier (PIID or FAIN). |
| `generatedInternalId` | USAspending generated unique award identifier. |
| `recipientName` | Recipient legal name. |
| `recipientUei` | Recipient Unique Entity Identifier. |
| `awardAmount` | Award obligation amount in US dollars, as returned by USAspending; not necessarily the contract ceiling. |
| `awardingAgency` | Awarding toptier agency name. |
| `awardingAgencyCode` | Awarding toptier agency code. |
| `awardingSubAgency` | Awarding subagency name. |
| `awardingSubAgencyCode` | Awarding subagency code. |
| `fundingAgency` | Funding agency name. |
| `fundingSubAgency` | Funding subagency name. |
| `contractAwardType` | Procurement award type; always null for grants. |
| `awardType` | Assistance award type label; generally null for contracts and IDVs. |
| `naicsCode` | NAICS industry code, flattened from NAICS.code. |
| `naicsDescription` | NAICS industry description. |
| `pscCode` | Product or service code, flattened from PSC.code. |
| `pscDescription` | Product or service description. |
| `placeOfPerformanceCity` | Primary place of performance city name. |
| `placeOfPerformanceState` | Primary place of performance state code. |
| `placeOfPerformanceCountry` | Primary place of performance country name, or country code if name is missing. |
| `placeOfPerformanceZip` | Primary place of performance five-digit ZIP code. |
| `startDate` | Award start date returned by the API. |
| `endDate` | Award end date; may be absent, especially for IDVs. Last Date to Order is not substituted. |
| `lastModifiedDate` | Last modification date returned by the API. |
| `baseObligationDate` | Base obligation date returned by the API. |
| `description` | Award description text. |
| `usaspendingUrl` | Public award page constructed from generatedInternalId. |

### FAQ

**Are these open solicitations?** No. These are spending awards already reported by federal agencies. Use them to study past spending, recipients, and agency demand.

**Can I search grants or IDVs?** Set `awardType` to `grants` or `idvs`. Grants use Award Type and omit contract-only NAICS/PSC fields. IDVs may have no end date; Last Date to Order is requested but is not treated as endDate.

**Why are there no results?** Try a broader date range and fewer filters. Agency names must be exact. Data depends on agency reporting and USAspending updates.

**Do the date fields match the award start date?** Not by default. Without `newAwardsOnly`, the official API matches the window to award activity (an older award can appear if it had a later action). Turn on `newAwardsOnly` — recommended for new-win lists — to return only awards whose base/start date falls in the window.

**How does pagination work?** The Actor uses one-based pages and follows `page_metadata.hasNext`, without assuming a total count. It pauses 250 ms between pages. The client retries network errors, HTTP 429 and 5xx up to four attempts, honors Retry-After, and uses exponential backoff with jitter. A first-page HTTP 400 can retry with limit 10; that limit remains fixed for later pages. Informational API messages do not fail the run.

**Is this a government product?** No. See the disclaimer below.

### Disclaimer

This Actor is not affiliated with, endorsed by, sponsored by, or operated by the U.S. government, USAspending.gov, the Bureau of the Fiscal Service, or the U.S. Department of the Treasury. It is an independent tool that requests data from the public [USAspending API](https://api.usaspending.gov/docs/endpoints).

### Local development

Requires Node.js 22 or newer. No secrets are required.

```sh
npm install
npm test
npm run build
npm start
```

Optional local input can be saved in `storage/key_value_stores/default/INPUT.json`. Tests use mocked fetch only and do not call the live API. Docker uses a TypeScript build stage and a production-only Node 22 runtime stage. Errors expose short safe status hints, never request or response bodies.

Generate the icon with `python3 scripts/make-icon.py` (requires Pillow). The PNG is supplied for later Apify Console upload; actor.json omits an unsupported icon property.

Official references: [USAspending API docs](https://api.usaspending.gov/docs/endpoints) and [spending_by_award endpoint contract](https://github.com/fedspendingtransparency/usaspending-api/blob/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_award.md).

# Actor input Schema

## `keywords` (type: `string`):

Filter awards by search text; use a string with commas between multiple keywords. Default: omitted, no keyword filter. Use to target a product or service. Example: "software,cloud".

## `naics` (type: `string`):

Filter by industry using a string of comma-separated NAICS prefixes, each 2–6 digits. Default: omitted, no NAICS filter. Use for industry-specific searches. Example: "541512,541511".

## `agency` (type: `string`):

Filter by the exact official awarding toptier agency name as a string. Default: omitted, all agencies. Use to research a specific federal buyer. Example: "Department of Defense".

## `recipientName` (type: `string`):

Search recipient names and identifiers using a text string. Default: omitted, all recipients. Use to research an award recipient or incumbent. Example: "LOCKHEED MARTIN".

## `awardDateFrom` (type: `string`):

Set the inclusive window start as YYYY-MM-DD or MM/dd/yyyy, no earlier than 2007-10-01. Default: 29 days before awardDateTo. Use for historical searches. Matches activity unless newAwardsOnly is true. Example: "2026-01-01".

## `awardDateTo` (type: `string`):

Set the inclusive window end as YYYY-MM-DD or MM/dd/yyyy, on or after awardDateFrom. Default: today UTC. Use to bound a historical search. Matches activity unless newAwardsOnly is true. Example: "2026-01-31".

## `newAwardsOnly` (type: `boolean`):

Set a JSON boolean to restrict the date window to award base/start dates using the API new_awards_only date_type. Default: false, which matches award activity and can include older awards with later actions. Use true for new-win lists. Example: true.

## `state` (type: `string`):

Filter place of performance using a two-letter US state, territory, or military code; lowercase is accepted. Default: omitted, no location filter. Use to target where work takes place. Example: "VA".

## `awardType` (type: `string`):

Choose one string: contracts, idvs (indefinite delivery vehicles), or grants. Default: "contracts". Use to switch the award category; grants omit contract-only NAICS/PSC output values. Example: "grants".

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

Limit the number of awards stored using a JSON integer from 1 to 10000. Default: 10. Use a smaller value for previews or a larger value for exports; charge limits may stop earlier. Example: 25.

## `pageSize` (type: `integer`):

Set the USAspending API page size using a JSON integer from 1 to 100. Default: 100. Use a smaller value when smaller API batches are useful; maxItems still caps stored awards. Example: 50.

## Actor input object example

```json
{
  "newAwardsOnly": false,
  "awardType": "contracts",
  "maxItems": 10,
  "pageSize": 100
}
```

# Actor output Schema

## `awards` (type: `string`):

Default dataset items: 27 documented fields per normalized award, including awardId, recipientName, awardAmount, and usaspendingUrl; missing values are null.

# 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 = {
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("samgov-tools/usaspending-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 = { "maxItems": 10 }

# Run the Actor and wait for it to finish
run = client.actor("samgov-tools/usaspending-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 '{
  "maxItems": 10
}' |
apify call samgov-tools/usaspending-awards --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,samgov-tools/usaspending-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/04doUoyNURFXrxsgo/builds/QLZDgB2lhVPSRXfGM/openapi.json