# USAspending Federal Awards: Contracts, IDVs & Grants (`studded_lantana/usaspending-awards`) Actor

US federal contract, IDV and grant awards from the official USAspending API: recipient, amount, agency, NAICS/PSC, dates. Filter by keyword, recipient, agency, state, code and amount.

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

## Pricing

from $2.00 / 1,000 awards

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 Federal Awards: Contracts, IDVs & Grants

**What it does:** returns US federal awards from the official **USAspending.gov API** (US Treasury): contracts, indefinite-delivery vehicles (GWACs, IDIQs, BPAs, FSS) and grants/cooperative agreements. Each award comes as one flat record with recipient, amount, outlays, awarding and funding agency, NAICS/PSC codes or assistance listing, start/end dates and a link to the award page. Filter by keyword, recipient, awarding agency, NAICS, PSC, assistance listing, place-of-performance state, amount range and date range.

Why use it: it calls the documented public API directly (no HTML scraping), handles the API's one-award-group-per-search rule for you, and costs **$2 per 1,000 awards**.

### Use cases

- **Track a competitor or partner.** List the federal contracts and grants one company has received, by name or UEI.
- **Size a market.** Pull every award in a NAICS or PSC code, an agency or a state, and total the amounts.
- **Find leads.** Companies that just won a federal award often need subcontractors, staff and suppliers.
- **Follow grant money.** See which organisations receive funding under a given assistance listing.
- **Feed other tools.** Results are plain JSON records, so they drop into a spreadsheet, a BI tool or an AI agent.

**Tutorial:** [How to find who is winning federal cybersecurity contracts (without writing API code)](https://dev.to/kim_kelsi_b2078fa69a/how-to-find-who-is-winning-federal-cybersecurity-contracts-without-writing-api-code-55ed)

### Input

```json
{
  "awardTypes": ["contracts", "idvs"],
  "daysBack": 30,
  "keywords": ["cybersecurity"],
  "agency": "Department of Defense",
  "naicsCodes": ["541512"],
  "states": ["VA"],
  "minAmount": 100000,
  "sortBy": "amount",
  "maxItems": 500
}
```

- `awardTypes`: `contracts` (definitive contracts, purchase orders, delivery orders, BPA calls), `idvs` (GWACs, IDIQs, BPAs, FSS) and/or `grants` (block, formula and project grants and cooperative agreements). Direct payments, loans and insurance are not offered, because they mostly go to individuals.
- `daysBack` (default 30) or `dateFrom` / `dateTo` (`YYYY-MM-DD`, from 2007-10-01). This is USAspending's time-period filter: awards with an action in the period.
- `keywords`: USAspending keyword search, at least 3 characters each.
- `recipient`: recipient name or UEI search text.
- `agency`: the **exact** top-tier awarding agency name, e.g. `Department of Energy`. A name that doesn't match returns no results.
- `naicsCodes`, `pscCodes`: contracts and IDVs only. `assistanceListings` (e.g. `93.778`): grants only. Filters that don't apply to an award type are ignored for that type, and the log says so.
- `states`: place-of-performance state or territory codes.
- `minAmount` / `maxAmount` (USD), `sortBy` (`amount`, `start_date` or `last_modified`, all newest/largest first), `maxItems` (default 500; at most 10,000 per award type).

### Output

One record per award. A real example (contract, NAICS 541512, Virginia, fetched 2026-10-09):

```json
{
  "award_id": "47QFCA21F0001",
  "award_group": "contracts",
  "award_type": "DELIVERY ORDER",
  "recipient_name": "SCIENCE APPLICATIONS INTERNATIONAL CORPORATION",
  "recipient_uei": "MMLKPW9JLX64",
  "recipient_city": "RESTON",
  "recipient_state": "VA",
  "recipient_country": "UNITED STATES",
  "recipient_withheld": false,
  "amount": 1205937997.76,
  "total_outlays": -280276.75,
  "description": "THE SCOPE OF THE TO IS TO PROVIDE ENTERPRISE IT SERVICES FOR THE USACE.",
  "awarding_agency": "General Services Administration",
  "awarding_sub_agency": "Federal Acquisition Service",
  "funding_agency": "Department of Defense",
  "naics_code": "541512",
  "naics_description": "COMPUTER SYSTEMS DESIGN SERVICES",
  "psc_code": "DA01",
  "psc_description": "IT AND TELECOM - BUSINESS APPLICATION/APPLICATION DEVELOPMENT SUPPORT SERVICES (LABOR)",
  "assistance_listings": [],
  "start_date": "2020-11-30",
  "end_date": "2026-11-27",
  "last_date_to_order": null,
  "base_obligation_date": "2020-11-30",
  "last_modified": "2026-09-21 14:03:34",
  "place_of_performance_state": "VA",
  "place_of_performance_country": "USA",
  "url": "https://www.usaspending.gov/award/CONT_AWD_47QFCA21F0001_4732_47QTCK18D0001_4732",
  "fetched_at": "2026-10-09T18:38:37Z"
}
```

| Field | Meaning |
|---|---|
| `award_id`, `award_group`, `award_type` | PIID/FAIN, the group you asked for, and the award type as USAspending names it |
| `recipient_name`, `recipient_uei`, `recipient_city`, `recipient_state`, `recipient_country` | The recipient (organisations only, see Limits) |
| `recipient_withheld` | `true` when the recipient may be an individual, so its name, UEI, city and state are left empty |
| `amount`, `total_outlays` | Award amount (obligations, or face value for IDVs) and outlays to date, USD |
| `description` | Award description (cut at 2,000 characters; emails and phone numbers replaced) |
| `awarding_agency`, `awarding_sub_agency`, `funding_agency` | Agencies |
| `naics_code`, `naics_description`, `psc_code`, `psc_description` | Contracts and IDVs |
| `assistance_listings` | Grants: assistance listing (CFDA) number and program title |
| `start_date`, `end_date`, `last_date_to_order`, `base_obligation_date`, `last_modified` | Dates (`last_date_to_order` for IDVs) |
| `place_of_performance_state`, `place_of_performance_country` | Where the work is done |
| `url` | The award page on USAspending.gov |

### FAQ

**How do I get USAspending data without writing API code?**
Run the Actor with the filters you want. Results land in an Apify dataset, which you can download as JSON, CSV or Excel, or read through the Apify API.

**How do I find the federal contracts a company has won?**
Set `recipient` to the company name or its UEI, set `awardTypes` to `["contracts", "idvs"]`, and widen `daysBack` (for example 365) or set `dateFrom`.

**Why does my agency filter return nothing?**
`agency` must be the exact top-tier name in full, such as `Department of Defense` or `General Services Administration`. Abbreviations like `DoD` or `GSA` do not match.

**What is an IDV?**
An indefinite-delivery vehicle: a contract such as a GWAC, IDIQ, BPA or Federal Supply Schedule that agencies place orders against later. Its `amount` is the vehicle's face value, and `last_date_to_order` is the last day orders can be placed.

**Why is the recipient name empty on some awards?**
`recipient_withheld` is `true` when the recipient may be an individual, or when USAspending itself hides the name. The award page in `url` has the full record. See Limits.

**Is this the same as SAM.gov contract opportunities?**
No. This Actor returns awards that have already been made, as reported on USAspending.gov. It does not return open solicitations.

**How far back does it go?**
To 2007-10-01, the start of USAspending's award search.

### Pricing

Pay per event:

- **$0.005 per run** (start).
- **$0.002 per award** returned, so $2 per 1,000 awards.

Set a maximum charge per run in Apify to cap spend.

### Limits

- **Recipients are named only when they are clearly organisations:** a legal-entity word (Inc, LLC, Corp, Company, Ltd, LLP, PLLC, P.C. and similar), or a public or non-profit body (university, college, state/city/county, department, agency, government, institute, institution, foundation, association, hospital, tribe, center, fund...). Anyone else may be a sole proprietor, i.e. a person, so `recipient_withheld` is `true` and the name, UEI, city and state are left out. The award page (`url`) has the full record. In samples from September–October 2026, 4% of contracts, 4% of IDVs and 6% of the grants that USAspending itself names were withheld. Some real companies whose names carry no legal suffix are also withheld (e.g. "General Atomics"). Street addresses are never returned.
- USAspending itself hides recipients of grants to individuals as `REDACTED DUE TO PII`. Those records are returned with `recipient_withheld: true`. In one sample of 600 recent grants, 198 were like this.
- Assistance (grant) data is reported by agencies in batches, so the newest grants can appear days to weeks after the action date.
- USAspending's search covers actions from 2007-10-01. Up to 100 pages of 100 awards per award type per run.
- Data is US government work (public domain), from api.usaspending.gov. This Actor is not affiliated with or endorsed by the US Treasury or USAspending.gov.

# Actor input Schema

## `awardTypes` (type: `array`):

contracts = definitive contracts, purchase orders, delivery orders and BPA calls; idvs = indefinite-delivery vehicles (GWACs, IDIQs, BPAs, FSS); grants = block, formula and project grants and cooperative agreements. Direct payments, loans and insurance are not offered.

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

How far back to look: awards with an action in the last N days, including today (UTC). Use 30 for the last month or 365 for the last year. Ignored if Date from is set.

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

Optional start of a fixed period, as YYYY-MM-DD (e.g. "2025-10-01" for the start of US fiscal year 2026). Use it with Date to instead of Days back. Must be on or after 2007-10-01.

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

Optional. YYYY-MM-DD, inclusive. Defaults to today (UTC).

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

USAspending keyword search, e.g. \["cybersecurity"]. Each keyword needs at least 3 characters and is matched against award descriptions, recipients and codes. Use specific terms; to search for one company, use Recipient instead.

## `recipient` (type: `string`):

Optional. The company or organisation that received the award: a name or part of one (e.g. "Lockheed Martin") or a 12-character UEI. Use this to list what one recipient has won.

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

Optional. The awarding agency, as its exact top-tier name in full, not an abbreviation: e.g. "Department of Defense", "Department of Health and Human Services", "Department of Energy", "Department of Veterans Affairs", "Department of Homeland Security", "General Services Administration", "National Aeronautics and Space Administration". A name that does not match exactly returns no results.

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

Industry filter for contracts and IDVs (ignored for grants). 2- to 6-digit NAICS codes; a shorter code covers everything under it, e.g. "541512" (computer systems design services) or "54" (all professional, scientific and technical services).

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

Product or service filter for contracts and IDVs (ignored for grants). Federal product/service codes (PSC), e.g. "D399" or "R4".

## `assistanceListings` (type: `array`):

Program filter for grants (ignored for contracts and IDVs). Assistance listing numbers, formerly CFDA numbers, e.g. "93.778".

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

Where the work is performed, as two-letter US state or territory codes, e.g. \["VA", "TX"]. This is the place of performance, not the recipient's home state.

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

Keep awards of at least this many US dollars, e.g. 100000. Leave empty for no lower limit.

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

Keep awards of at most this many US dollars, e.g. 5000000. Leave empty for no upper limit.

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

Order of results: largest award amount, newest start date or most recently modified first.

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

Stop after this many awards. You are charged per award returned, so this also caps the cost of the run. Results come in the Sort by order, so a small number with Sort by = amount gives the largest awards. Up to 10,000 per award type.

## Actor input object example

```json
{
  "awardTypes": [
    "contracts"
  ],
  "daysBack": 30,
  "keywords": [
    "cybersecurity"
  ],
  "sortBy": "amount",
  "maxItems": 500
}
```

# Actor output Schema

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

One record per federal award: recipient (organisations only), amount, agency, NAICS/PSC or assistance listing, dates and USAspending link.

# 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": [
        "cybersecurity"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("studded_lantana/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 = { "keywords": ["cybersecurity"] }

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

```

## MCP server setup

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