# USAspending.gov Awards Scraper (`datamule/usaspending-gov-awards-scraper`) Actor

Scrape U.S. federal awards from the official USAspending.gov API. Query contracts, grants, loans & assistance by recipient, agency, NAICS/PSC, date & amount. One record per award — recipient, amount, agency, dates, codes + raw. Pay per award.

- **URL**: https://apify.com/datamule/usaspending-gov-awards-scraper.md
- **Developed by:** [Datamule](https://apify.com/datamule) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 award records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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.gov Awards Scraper

Scrape U.S. federal award records — **contracts, grants, loans and other
financial assistance** — from the **official USAspending.gov API**
(`https://api.usaspending.gov/api/v2/search/spending_by_award`), the U.S.
Treasury's public system of record for federal spending. No API key, no login.
One clean dataset record per award, with a unified set of normalized columns
plus the complete raw award object so nothing is lost.

### What it does

Pick an **award category** (`awardGroup`) — USAspending requires every award
type in a single query to belong to one category — then filter it any way you
like (the API ANDs the filters together):

| Input | API filter | Example |
|-------|-----------|---------|
| `awardGroup` | award category | `contracts`, `grants`, `loans` |
| `keywords` | free-text over the whole award | `cybersecurity`, `cloud` |
| `recipientSearch` | recipient (company/org) name | `Lockheed Martin` |
| `awardingAgency` | awarding top-tier agency | `Department of Defense` |
| `naicsCodes` | NAICS industry code(s) | `541519` |
| `pscCodes` | PSC product/service code(s) | `D319` |
| `awardTypeCodes` | specific type codes within the category | `D` (definitive contracts) |
| `startDate` / `endDate` | award action-date window | `2020-01-01` → `2023-12-31` |
| `minAmount` / `maxAmount` | award-amount range (USD) | `1000000` → … |
| `sort` / `order` | result ordering | `amount` / `desc` |

`maxResults` caps how many awards you get; the actor paginates automatically
(up to 100 per request) until it reaches the cap or the result set is
exhausted.

#### Award categories

- **contracts** — BPA calls, purchase orders, delivery orders, definitive contracts
- **idvs** — indefinite-delivery vehicles (GWAC, IDC, FSS schedules, BOA, BPA)
- **grants** — block / formula / project grants + cooperative agreements
- **loans** — direct & guaranteed/insured loans
- **other\_financial\_assistance** — direct payments for specified / unrestricted use
- **direct\_payments** — insurance, other financial assistance, etc.

### Output

One dataset record per award. The source columns differ by category (contracts
carry NAICS/PSC + a contract award type; assistance awards carry a CFDA program

- an assistance award type; loans carry a loan value / subsidy cost instead of
  an obligated amount) — so every record is flattened onto **one unified schema**:

`awardId`, `awardGroup`, `awardType`, `recipientName`, `recipientUei`,
`recipientId`, `awardAmount`, `totalOutlays`, `loanValue`, `subsidyCost`,
`awardingAgency`, `awardingSubAgency`, `fundingAgency`, `fundingSubAgency`,
`periodOfPerformanceStart`, `periodOfPerformanceEnd`, `lastModifiedDate`,
`baseObligationDate`, `description`, `naicsCode`, `naicsDescription`, `pscCode`,
`pscDescription`, `cfdaNumber`, `cfdaProgramTitle`, `assistanceListings`,
`recipientLocation` (city / state / country), `placeOfPerformance` (city /
state / country), `defCodes`, `covid19Obligations`, `covid19Outlays`,
`infrastructureObligations`, `infrastructureOutlays`, `awardUrl`,
`generatedInternalId`

…plus **`raw`** — the complete, untouched award object from the API — so any
field not surfaced above is still available.

### Example input

```json
{
  "awardGroup": "contracts",
  "keywords": ["cloud"],
  "awardingAgency": "Department of Defense",
  "startDate": "2020-01-01",
  "minAmount": 1000000,
  "sort": "amount",
  "order": "desc",
  "maxResults": 200
}
```

A query that matches nothing returns **0 records and succeeds** (never an
error).

### Notes & limits

- USAspending's searchable award history starts at **2007-10-01**. For older
  data (back to 2000-10-01) use USAspending's bulk-download endpoints.
- Deep paging is capped at roughly **10,000 records per query** — refine your
  filters (agency, date window, amount) to reach the rest.
- NAICS/PSC codes are only populated on **contract-type** awards; CFDA program
  info only on **assistance** awards. Non-applicable columns come back `null`.

### Pricing

Pay-per-event: charged per award returned.

### Source

Data comes from the U.S. Department of the Treasury's USAspending.gov API
(<https://api.usaspending.gov/docs/endpoints>). USAspending.gov data is in the
public domain. This actor is an independent tool and is not affiliated with or
endorsed by the U.S. Treasury or any federal agency.

# Actor input Schema

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

Which category of federal award to search. USAspending requires all award types in one query to belong to a single category, so pick one per run. Contracts = procurement (BPA calls, purchase/delivery orders, definitive contracts). IDVs = indefinite-delivery vehicles (GWAC, IDC, FSS schedules). Grants = block/formula/project grants + cooperative agreements. Loans = direct & guaranteed loans. Other financial assistance / Direct payments = the remaining assistance types.

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

Free-text search across the whole award record (maps to the API's keywords filter). e.g. "cybersecurity", "cloud migration", "vaccine". One term per line, or comma-separated. Combine with the filters below.

## `recipientSearch` (type: `string`):

Search by recipient name — the company, university, state, or organization that received the award (recipient\_search\_text). e.g. "Lockheed Martin", "Johns Hopkins University". One per line, or comma-separated.

## `awardingAgency` (type: `string`):

Filter to a single awarding top-tier agency, by its full name. e.g. "Department of Defense", "Department of Health and Human Services", "National Aeronautics and Space Administration". Leave empty for all agencies.

## `naicsCodes` (type: `string`):

Filter contracts/IDVs by one or more NAICS industry codes. e.g. "541519" (other computer related services), "541512" (computer systems design). One per line, or comma-separated. (NAICS is only populated on contract-type awards.)

## `pscCodes` (type: `string`):

Filter contracts/IDVs by one or more PSC (Product & Service) codes. e.g. "D319" (IT & telecom other), "R425" (engineering technical services). One per line, or comma-separated. (PSC is only populated on contract-type awards.)

## `awardTypeCodes` (type: `string`):

Advanced: narrow to specific award type codes WITHIN the selected category. e.g. for Contracts, "D" = only definitive contracts; for Grants, "04" = only project grants. Must belong to the chosen award category. Leave empty to include every type in the category.

## `startDate` (type: `string`):

Only awards with an action date on or after this date (YYYY-MM-DD). USAspending's searchable history starts at 2007-10-01. Leave empty for no lower bound.

## `endDate` (type: `string`):

Only awards with an action date on or before this date (YYYY-MM-DD). Leave empty for no upper bound.

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

Only awards with an amount at or above this value (US dollars). Leave empty for no minimum.

## `maxAmount` (type: `integer`):

Only awards with an amount at or below this value (US dollars). Leave empty for no maximum.

## `sort` (type: `string`):

Field to sort results by. Amount / Outlays / Start date / End date / Last modified / Recipient / Award ID apply to contracts, grants and assistance; Loan value / Subsidy cost apply to loans. If a sort field doesn't apply to the chosen award category, the actor falls back to that category's default so the query always succeeds.

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

Ascending or descending.

## `maxResults` (type: `integer`):

Maximum number of award records to return. The actor paginates automatically at up to 100 per request until this many are collected or the result set is exhausted. Note: USAspending caps deep paging at roughly 10,000 records per query — refine your filters to reach the rest.

## `limit` (type: `integer`):

Awards fetched per API request (1–100). Larger pages = fewer requests. Usually leave at the default.

## Actor input object example

```json
{
  "awardGroup": "contracts",
  "keywords": "cloud",
  "minAmount": 1000000,
  "sort": "amount",
  "order": "desc",
  "maxResults": 100,
  "limit": 100
}
```

# Actor output Schema

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

No description

# 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 = {
    "keywords": "cloud",
    "recipientSearch": "",
    "awardingAgency": "",
    "naicsCodes": "",
    "pscCodes": "",
    "awardTypeCodes": "",
    "startDate": "",
    "endDate": "",
    "minAmount": 1000000,
    "maxResults": 100,
    "limit": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/usaspending-gov-awards-scraper").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 = {
    "keywords": "cloud",
    "recipientSearch": "",
    "awardingAgency": "",
    "naicsCodes": "",
    "pscCodes": "",
    "awardTypeCodes": "",
    "startDate": "",
    "endDate": "",
    "minAmount": 1000000,
    "maxResults": 100,
    "limit": 100,
}

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

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

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

```

## CLI example

```bash
echo '{
  "keywords": "cloud",
  "recipientSearch": "",
  "awardingAgency": "",
  "naicsCodes": "",
  "pscCodes": "",
  "awardTypeCodes": "",
  "startDate": "",
  "endDate": "",
  "minAmount": 1000000,
  "maxResults": 100,
  "limit": 100
}' |
apify call datamule/usaspending-gov-awards-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datamule/usaspending-gov-awards-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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