# USAspending Scraper — Federal Contract Awards & Recipients (`devilscrapes/usaspending-federal-awards-scraper`) Actor

Search USAspending.gov's public Award Search API and export federal contract award records — recipient, amount, agency, dates — for govcon lead generation and competitive intelligence, filtered by keyword, recipient, agency, award type and date range.

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

## Pricing

Pay per event

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

<div align="center">
  <img src=".actor/icon.svg" width="160" alt="Devil Scrapes mark" />

## USAspending Federal Awards Scraper

**💰 $3.05 / 1 000 results**  ·  pay only for results  ·  no credit card to try

*We do the dirty work so your dataset stays clean.* 😈

Search USAspending.gov's public Award Search API and export federal contract award records — recipient, amount, agency, dates — for govcon lead generation and competitive intelligence, filtered by keyword, recipient, agency, award type and date range.

</div>

***

> **Quick answer:** The **USAspending Federal Awards Scraper** searches USAspending.gov's public Award Search API and exports federal contract awards — recipient, amount, agency and dates, plus a ready-made USAspending.gov profile link — into JSON, CSV or Excel, filtered by keyword, recipient, agency, award type and date range. The API is keyless but unforgiving: it needs a precise POST body with a non-empty, enum-validated `award_type_codes` list or the whole request 422s, and it ships no total-count field, so paging has to stop on `hasNext == false` rather than an assumed page count. We build that request correctly and treat zero matches as a clean success, not a failed run. Pricing is pay-per-result — **$3.05 per 1 000 awards**, no subscription, no card required to try it.

### 🎯 What this scrapes

USAspending.gov publishes every federal contract award, but its Award Search API expects a precise POST body — a non-empty, enum-validated award\_type\_codes list is mandatory or the whole request 422s, paging has no total-count field so you must stop on hasNext == false, and a narrow filter combination legitimately returns zero rows rather than an error. This Actor builds that request correctly, pages until the API says there is nothing left, and flattens each award — recipient, amount, agency, dates — into one billable row with a ready-made USAspending.gov profile link.

### 🔥 What we handle for you

- 🧵 **Pagination done right** — we page on USAspending's `page`/`limit` cursor and stop exactly on `hasNext == false`, never on an assumed page count.
- 🛡️ **A bad award type code never reaches the API** — validated against the live-confirmed enum before your run is charged a cent.
- 🔁 **Retries with exponential backoff** on `429 / 5xx`, honouring `Retry-After` — up to 5 attempts per page.
- 🧱 **Zero matches is a clean success, not a failure** — a narrow filter combination finishes SUCCEEDED with a status message, never a false FAILED run.
- 🧊 **Clean, typed dataset rows** — Pydantic-validated, stable award IDs, ready-made USAspending.gov profile links.
- 💰 **Pay-Per-Event pricing** — you only pay for results that hit your dataset.

### 💡 Use cases

- Govcon lead generation — find which contractors are winning awards from a target agency.
- Competitive intelligence — track a competitor's federal contract wins by recipient name.
- Market sizing — pull the biggest awards in a date window and agency to size a federal market.
- Journalism and watchdog research — follow the money on a keyword or agency across a time period.

### ⚙️ How to use it

1. Click **Try for free** at the top of the page.
2. Fill in the input form — most fields have sensible defaults.
3. Click **Start**. Output streams into the run's dataset.
4. Export from **Storage → Dataset** as JSON, CSV, or Excel — or fetch via the API.

### 📥 Input

| Field | Type | Required | Default | Notes |
|---|---|:--:|---|---|
| `keywords` | `array` | no | '—' | Free-text keyword search — matches award, recipient, or agency text. |
| `recipientSearchText` | `array` | no | '—' | Match awards by recipient (company) name, e.g. <code>Lockheed</code>. |
| `awardingAgencyName` | `string` | no | '—' | Top-tier awarding agency name, e.g. <code>Department of Defense</code>. |
| `awardTypeCodes` | `array` | no | \['A', 'B', 'C', 'D'] | Award type codes to include. Defaults to the four prime-contract types (<code>A</code>, <code>B</code>, <code>C</code>,… |
| `timePeriodStart` | `string` | no | '2024-01-01' | Start of the award action date window, as <code>YYYY-MM-DD</code>. The API's documented floor is… |
| `timePeriodEnd` | `string` | no | '2024-12-31' | End of the award action date window, as <code>YYYY-MM-DD</code>. Must be on or after the start date. |
| `sortField` | `string` | no | 'Award Amount' | Field the API sorts results by. |
| `sortOrder` | `string` | no | 'desc' | Sort direction. |
| `maxResults` | `integer` | no | 100 | Stop once this many award rows have been emitted. Each row is one billed result event. |
| `proxyConfiguration` | `object` | no | {'useApifyProxy': False} | USAspending.gov is a public keyless API and does not need a proxy. Leave this off unless your account requires egress… |

#### Example input

```json
{
  "recipientSearchText": [
    "Lockheed"
  ],
  "awardTypeCodes": [
    "A",
    "B",
    "C",
    "D"
  ],
  "timePeriodStart": "2024-01-01",
  "timePeriodEnd": "2024-12-31",
  "maxResults": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

### 📤 Output

Every row is one dataset item.

| Field | Type | Notes |
|---|---|---|
| `award_id` | `string` | Award ID, e.g. `N0001917C0001`. |
| `generated_internal_id` | `string` | Stable internal award identifier used for cross-referencing and building the profile URL. |
| `recipient_name` | `string` | Recipient (company or entity) name. |
| `award_amount` | `number` | Award amount in USD. |
| `awarding_agency` | `string` | Top-tier awarding agency, e.g. `Department of Defense`. |
| `awarding_sub_agency` | `string` | Awarding sub-agency, e.g. `Department of the Navy`. |
| `funding_agency` | `string` | Top-tier funding agency. |
| `award_type` | `string` | Contract award type, e.g. `DEFINITIVE CONTRACT`. |
| `start_date` | `string` | Award period of performance start date. |
| `end_date` | `string` | Award period of performance end date. |
| `description` | `string` | Free-text award description. Often null. |
| `agency_slug` | `string` | Agency slug used to build the USAspending.gov profile URL. |
| `usaspending_url` | `string` | Public USAspending.gov award profile page. |

#### Example output

```json
{
  "award_id": "N0001917C0001",
  "generated_internal_id": "CONT_AWD_N0001917C0001_9700_-NONE-_-NONE-",
  "recipient_name": "LOCKHEED MARTIN CORPORATION",
  "award_amount": 35135514910.2,
  "awarding_agency": "Department of Defense",
  "awarding_sub_agency": "Department of the Navy",
  "funding_agency": "Department of Defense",
  "award_type": "DEFINITIVE CONTRACT",
  "start_date": "2017-11-17",
  "end_date": "2031-03-31",
  "description": "LRIP LOT 12 ADVANCE ACQUISITION CONTRACT",
  "agency_slug": "department-of-defense",
  "usaspending_url": "https://www.usaspending.gov/award/CONT_AWD_N0001917C0001_9700_-NONE-_-NONE-"
}
```

### 💰 Pricing

Pay-Per-Event — you pay only when these events fire:

| Event | USD | What it is |
|---|---:|---|
| `actor-start` | $0.05 | One-off warm-up charge per run |
| `result` | $0.003 | Per dataset item |

Example: 1 000 results at the rates above ≈ **$3.05**. No subscription, no minimum, no card to start — Apify gives every new account $5 of free credit.

### 🚧 Limitations

- Prime-award level only in v1 — no sub-award (subcontractor) drill-down.
- No recipient or agency profile enrichment — fields come from the award search response itself.
- Deep pagination beyond 10,000 results requires a cursor-based approach USAspending documents separately; this Actor caps maxResults at 10,000.

### ❓ FAQ

**Do I need an API key?**

No. USAspending.gov's Award Search API is public and keyless — no auth, no account required.

**Why must I set award type codes?**

The API rejects a request with an empty or missing award\_type\_codes filter. The Actor defaults to the four prime-contract types (A, B, C, D) so a first run always works, and validates any code you add against the API's live enum before charging you.

**What happens if my filters match nothing?**

The run finishes successfully with zero rows and a status message describing what was searched — a narrow filter combination legitimately returning no awards is not an error.

**How far back does the data go?**

USAspending.gov's documented floor is 2007-10-01. Earlier start dates are accepted but return no data before that floor.

### 💬 Your feedback

Spotted a bug, hit a weird edge case, or need a new field? Open an
issue on the Actor's **Issues** tab on Apify Console — we ship
fixes weekly and we read every report.

***

<div align="center">

Built by **[Devil Scrapes](https://apify.com/DevilScrapes)** 😈 — a small fleet of
opinionated public-data Actors. Honest pricing, real engineering, zero fine print.

</div>

# Actor input Schema

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

Free-text keyword search — matches award, recipient, or agency text.

## `recipientSearchText` (type: `array`):

Match awards by recipient (company) name, e.g. <code>Lockheed</code>.

## `awardingAgencyName` (type: `string`):

Top-tier awarding agency name, e.g. <code>Department of Defense</code>.

## `awardTypeCodes` (type: `array`):

Award type codes to include. Defaults to the four prime-contract types (<code>A</code>, <code>B</code>, <code>C</code>, <code>D</code>). The full valid set also includes IDV codes (<code>IDV\_A</code>..<code>IDV\_E</code>), grant codes (<code>02</code>..<code>11</code>) and loan codes (<code>F001</code>..<code>F010</code>). This field must never be empty — the API rejects a request with no award type codes.

## `timePeriodStart` (type: `string`):

Start of the award action date window, as <code>YYYY-MM-DD</code>. The API's documented floor is <code>2007-10-01</code>.

## `timePeriodEnd` (type: `string`):

End of the award action date window, as <code>YYYY-MM-DD</code>. Must be on or after the start date.

## `sortField` (type: `string`):

Field the API sorts results by.

## `sortOrder` (type: `string`):

Sort direction.

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

Stop once this many award rows have been emitted. Each row is one billed result event.

## `proxyConfiguration` (type: `object`):

USAspending.gov is a public keyless API and does not need a proxy. Leave this off unless your account requires egress through Apify Proxy.

## Actor input object example

```json
{
  "awardTypeCodes": [
    "A",
    "B",
    "C",
    "D"
  ],
  "timePeriodStart": "2024-01-01",
  "timePeriodEnd": "2024-12-31",
  "sortField": "Award Amount",
  "sortOrder": "desc",
  "maxResults": 100,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

All dataset items as JSON.

## `datasetItemsCsv` (type: `string`):

Same data exported to CSV.

## `datasetView` (type: `string`):

Open the run dataset in the Console.

# 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 = {
    "awardTypeCodes": [
        "A",
        "B",
        "C",
        "D"
    ],
    "timePeriodStart": "2024-01-01",
    "timePeriodEnd": "2024-12-31",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("devilscrapes/usaspending-federal-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 = {
    "awardTypeCodes": [
        "A",
        "B",
        "C",
        "D",
    ],
    "timePeriodStart": "2024-01-01",
    "timePeriodEnd": "2024-12-31",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("devilscrapes/usaspending-federal-awards-scraper").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 '{
  "awardTypeCodes": [
    "A",
    "B",
    "C",
    "D"
  ],
  "timePeriodStart": "2024-01-01",
  "timePeriodEnd": "2024-12-31",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call devilscrapes/usaspending-federal-awards-scraper --silent --output-dataset

```

## MCP server setup

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

```

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/rzZyPl8RDy9kTl9y4/builds/aCS0i05ztlP29XU8Q/openapi.json