# USAspending Federal Awards Scraper (`muhammadafzal/usaspending-awards-scraper`) Actor

Search official USAspending federal awards by category, recipient, agency, date, location, keyword, amount, and award ID. Export normalized JSON for research and agent workflows.

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

## Pricing

from $1.00 / 1,000 usaspending award results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Scraper

Search and export normalized U.S. federal prime-award records from the official, public USAspending data interface. This Actor is designed for procurement research, grant discovery, recipient analysis, agency monitoring, market intelligence, and agent workflows that need stable JSON instead of category-specific API fields.

The Actor supports contracts, grants, loans, direct payments, other financial assistance, and indefinite delivery vehicles (IDVs). It does not scrape subawards, transaction histories, attachments, or bulk files.

### What it extracts

| Field | Meaning |
|---|---|
| `awardId`, `generatedAwardId` | Public award ID and USAspending's stable generated ID |
| `awardCategory`, `awardType` | Normalized category and source award type |
| `recipientName`, `recipientUei` | Prime recipient name and UEI |
| `awardAmount` | Award Amount, or Loan Value for loans |
| `loanValue`, `subsidyCost`, `totalOutlays` | Category-specific financial values |
| `awardingAgency`, `fundingAgency` | Top-tier and sub-tier agency names |
| `description`, dates | Award purpose, start/issued date, end date, and last update |
| `naicsCode`, `pscCode` | Contract and IDV classification codes |
| `assistanceListings` | Assistance Listing/CFDA programs when supplied |
| locations | Recipient and primary place-of-performance geography |
| `sourceUrl`, `retrievedAt` | Public award page and retrieval provenance |

Every dataset item uses the same schema. Fields that do not apply to a category are explicitly `null` or an empty array, which makes multi-category exports safe to ingest into databases and AI tools.

### When to use it

Use this Actor to find awards by action-date period, recipient, exact top-tier agency name, U.S. state or territory, description keywords, known award IDs, or dollar range. It is especially useful when you need a bounded, normalized result set from several award categories.

Do not use it for pre-2007 award searches, subawards, individual transactions, federal account rollups, or a full warehouse export. USAspending recommends its download and bulk-download endpoints for older or very large extracts.

### Input

The default run queries 2025 contract awards, orders them by amount, and returns at most 100 records. The Console prefill adds grants and lowers the result cap to 25 for a fast first run.

```json
{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "awardCategories": ["contracts", "grants"],
  "recipientSearchText": "Boeing",
  "placeOfPerformanceStates": ["CA", "WA"],
  "minAwardAmount": 1000000,
  "sortBy": "amount",
  "sortOrder": "desc",
  "maxResults": 100,
  "pageSize": 100
}
```

Agency filters use exact top-tier agency names such as `Department of Defense`, not abbreviations or codes. State filters use two-letter U.S. state or territory codes. All supplied filter groups are combined by USAspending; values inside a list follow USAspending's documented list semantics.

For multiple award categories, the Actor queries each category through its compatible field set, normalizes the records, then applies one combined sort and result cap. Loans use `Loan Value` as the normalized `awardAmount`.

### Output example

```json
{
  "awardId": "HT940216C0001",
  "generatedAwardId": "CONT_AWD_HT940216C0001_9700_-NONE-_-NONE-",
  "internalId": 307885715,
  "awardCategory": "contracts",
  "awardType": "DEFINITIVE CONTRACT",
  "recipientName": "HUMANA GOVERNMENT BUSINESS INC",
  "recipientUei": "ZE6ZM6NKSV43",
  "recipientId": "1068e466-707d-6b6f-367f-0255fab79b8c-C",
  "awardAmount": 51269205263.03,
  "loanValue": null,
  "subsidyCost": null,
  "totalOutlays": 0,
  "awardingAgency": "Department of Defense",
  "awardingSubAgency": "Defense Health Agency",
  "fundingAgency": "Department of Defense",
  "fundingSubAgency": "Defense Health Agency",
  "description": "IGF::OT::IGF",
  "startDate": "2016-08-01",
  "endDate": "2025-12-31",
  "lastModifiedDate": "2026-02-10 17:52:09",
  "naicsCode": "524114",
  "naicsDescription": "DIRECT HEALTH AND MEDICAL INSURANCE CARRIERS",
  "pscCode": "Q201",
  "pscDescription": "MEDICAL- MANAGED HEALTHCARE",
  "assistanceListings": [],
  "recipientLocation": { "countryCode": "USA", "stateCode": "KY", "cityName": "LOUISVILLE", "postalCode": "40202" },
  "placeOfPerformance": { "countryCode": "USA", "stateCode": "KY", "cityName": "LOUISVILLE", "postalCode": "40201" },
  "sourceUrl": "https://www.usaspending.gov/award/CONT_AWD_HT940216C0001_9700_-NONE-_-NONE-/",
  "retrievedAt": "2026-08-28T12:00:00.000Z"
}
```

The `OUTPUT` key-value-store record classifies the run as `DATA`, `EMPTY`, `REJECTED`, `PARTIAL`, or `FAILED` and reports category coverage, pages fetched, result counts, charged events, warnings, and whether the charge limit stopped output.

### Pricing

This Actor uses pay per event.

| Event | Price | Charged when |
|---|---:|---|
| Actor start | $0.00005 | A run starts; handled automatically by Apify |
| USAspending award result | $0.001 | One normalized award is delivered to the default dataset |

Examples: 25 delivered records cost $0.02505; 100 cost $0.10005. Empty and rejected runs have no result-event charge. The Actor checks the SDK charge result after each delivered record and stops when the run's charge limit is reached.

### Reliability and limits

Data comes from USAspending's public endpoint, which currently requires no API key. Requests have a 30-second timeout and three bounded attempts with exponential backoff. Pagination uses the official response cursor, results are deduplicated by generated award ID, and partial valid data is preserved if one selected category fails.

`maxResults` is capped at 5,000 and the upstream page size at 100. A multi-category run may fetch up to `maxResults` candidates per category so the combined amount/date/ID sort remains correct. Narrow filters are faster and friendlier to the public service.

The action-date filter identifies awards with activity during the period; an award's original start date can therefore be earlier. USAspending may revise records after retrieval, and some fields are absent for some award categories.

### Responsible use and support

USAspending publishes official U.S. federal spending data. Follow applicable laws, USAspending terms, and your organization's data-governance rules. Recipient addresses may be public business or government records; avoid repurposing data for harassment, discrimination, or unrelated personal profiling.

For a reproducible bug report, include the redacted Actor input, run ID, affected award category, expected result, and observed `OUTPUT` warning. Do not include private credentials or unrelated personal data.

# Actor input Schema

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

Use this to set the first award action date included. Enter YYYY-MM-DD, for example 2025-01-01. USAspending Advanced Award Search supports dates from 2007-10-01 onward.

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

Use this to set the last award action date included. Enter YYYY-MM-DD, for example 2025-12-31. This is not the award's period-of-performance end date.

## `awardCategories` (type: `array`):

Use this to select one or more prime-award groups. Accepted values are contracts, grants, loans, directPayments, otherFinancialAssistance, and idvs. Defaults to contracts; this does not return subawards.

## `recipientSearchText` (type: `string`):

Use this to match one recipient name or identifier, for example BOEING. USAspending accepts one recipient search term; leave blank to include all recipients.

## `awardingAgencies` (type: `array`):

Use this to filter by exact top-tier awarding agency names, for example Department of Defense. These are names, not agency codes or sub-agencies.

## `fundingAgencies` (type: `array`):

Use this to filter by exact top-tier funding agency names, for example Department of Energy. These are names, not agency codes or awarding agencies.

## `placeOfPerformanceStates` (type: `array`):

Use this for U.S. place-of-performance states or territories. Enter two-letter codes such as CA or VA. This does not filter by recipient address.

## `recipientStates` (type: `array`):

Use this for recipient-address states or territories. Enter two-letter codes such as NY or TX. This does not filter the place of performance.

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

Use this to search USAspending award descriptions with terms such as cybersecurity. Leave empty for no description-keyword filter.

## `awardIds` (type: `array`):

Use this when specific PIIDs, FAINs, or URI award IDs are known, for example HT940216C0001. This is not USAspending's generated internal ID.

## `minAwardAmount` (type: `number`):

Use this to include awards at or above a dollar amount, for example 1000000. For loans the normalized amount is Loan Value; omit for no lower bound.

## `maxAwardAmount` (type: `number`):

Use this to include awards at or below a dollar amount, for example 5000000. Omit for no upper bound; it must not be below the minimum.

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

Use this to order the combined normalized results by amount, lastModifiedDate, or awardId. Amount means Loan Value for loan awards. Defaults to amount.

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

Use desc for highest/newest first or asc for lowest/oldest first. Defaults to desc; this applies across all selected categories.

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

Use this to cap delivered and billable award records. Enter 1–5000; default 100. At $0.001 per result, 100 records cost $0.10 plus the start event.

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

Use this to tune API pagination. Enter 1–100; default 100. Smaller pages reduce retry work but make more official API requests.

## Actor input object example

```json
{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "awardCategories": [
    "contracts",
    "grants"
  ],
  "sortBy": "amount",
  "sortOrder": "desc",
  "maxResults": 25,
  "pageSize": 100
}
```

# Actor output Schema

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

Schema-validated normalized USAspending award records.

## `dataset` (type: `string`):

Default dataset metadata and export links.

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

Outcome, record count, category coverage, warnings, and charged result-event count.

# 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 = {
    "startDate": "2025-01-01",
    "endDate": "2025-12-31",
    "awardCategories": [
        "contracts",
        "grants"
    ],
    "maxResults": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/usaspending-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 = {
    "startDate": "2025-01-01",
    "endDate": "2025-12-31",
    "awardCategories": [
        "contracts",
        "grants",
    ],
    "maxResults": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/usaspending-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 '{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "awardCategories": [
    "contracts",
    "grants"
  ],
  "maxResults": 25
}' |
apify call muhammadafzal/usaspending-awards-scraper --silent --output-dataset

```

## MCP server setup

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