# Federal Contract Awards Explorer (USAspending.gov) (`utility-belt-labs/contract-awards-explorer`) Actor

Search US federal contract and grant awards by keyword, NAICS, agency, recipient, state, date and amount. Competitor intel from official data.

- **URL**: https://apify.com/utility-belt-labs/contract-awards-explorer.md
- **Developed by:** [Utility Belt Labs](https://apify.com/utility-belt-labs) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

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

## Federal Contract Awards Explorer: competitor intel from USAspending.gov

**Search US federal contract awards, IDV contract vehicles and grants by keyword, NAICS, PSC, agency, recipient, state, date range and dollar amount.** Get clean rows with recipient, amount, awarding agency, dates, NAICS, award ID and a direct USAspending link. Or switch to **Top recipients** mode to rank the companies winning the most in a niche.

Uses the official public USAspending.gov API only (api.usaspending.gov). No API key, no scraping, no login.

### Use cases

- **Competitor research:** who won what, from which agency, for how much, and when does it end (recompete timing).
- **Capture and BD teams:** find the incumbents on contracts in your NAICS code and agency, and see how contracts were competed (number of offers, set-aside, pricing type).
- **Small businesses:** see which agencies buy your services in your state, filter by set-aside type and award size.
- **Market sizing:** how much did agency X spend on keyword Y over the last year?
- **Journalists and researchers:** pull transparent, linkable award records.
- **AI agents:** use it as a tool through the Apify MCP server ("which companies won cybersecurity contracts from DHS this year?").

### What you get

For each award (contracts, IDVs or grants):
`awardId`, `recipientName`, `recipientUei`, `awardAmount`, `totalOutlays`, `awardType`, `description`, `awardingAgency`, `awardingSubAgency`, `fundingAgency`, `startDate`, `endDate`, `lastModifiedDate`, recipient city/state, place-of-performance city/state/ZIP, `naicsCode` + description, `pscCode` + description (contracts and IDVs), `assistanceListings` (grants), `usaspendingUrl`, `recipientUrl`.

Turn on **Add competition details** (contracts and IDVs) to also get `extentCompeted`, `numberOfOffers`, `setAside`, `pricingType`, `solicitationProcedures`, `baseAndAllOptionsValue`, `potentialEndDate`, `parentAwardId` and `parentRecipientName`.

**Top recipients** mode returns `rank`, `recipientName`, `recipientUei`, `totalAwardAmount` (sum of the Award Amount of all awards matching your filters), `totalOutlays` and a link.

### Input

| Field | What it does |
|---|---|
| `mode` | `awards` (one row per award) or `topRecipients` (competitor ranking). |
| `awardCategory` | `contracts`, `idvs` (contract vehicles such as IDIQ/GWAC/BPA) or `grants`. |
| `keywords` | Search award text; several keywords are OR'd. 3+ characters each. |
| `recipientSearch` | Company names, UEI or DUNS text, e.g. `Booz Allen`. |
| `naicsCodes`, `pscCodes` | Industry and product/service codes (a short NAICS prefix such as `5415` includes all codes under it). |
| `awardingAgencies` | Top-tier agency names or abbreviations: `Department of Defense`, `DOD`, `GSA`, `HHS`... |
| `awardingSubAgencies` | Exact sub-agency names, e.g. `Department of the Navy`. |
| `recipientState`, `placeOfPerformanceState` | 2-letter state codes. |
| `startDate`, `endDate`, `daysBack` | Time period (default: last 365 days). Earliest supported: 2007-10-01. |
| `dateType` | `new_awards_only` (default: awards first signed in the period), `action_date`, `date_signed`, `last_modified_date`. |
| `minAmount`, `maxAmount` | Award Amount range in USD. |
| `setAsideCodes`, `recipientTypes` | Set-aside types (contracts/IDVs) and recipient business types (small business, woman-owned, veteran-owned...). |
| `awardIds` | Look up specific PIIDs/FAINs. |
| `sortBy`, `order`, `maxItems` | Sorting and result cap (up to 10,000). |
| `includeDetails` | Competition and pricing details (one extra API call per row). |

Example input:

```json
{
  "keywords": ["cybersecurity"],
  "awardingAgencies": ["DOD"],
  "startDate": "2025-10-01",
  "endDate": "2026-09-30",
  "minAmount": 1000000,
  "maxItems": 25,
  "includeDetails": true
}
```

### Example output (one row, shortened)

```json
{
  "awardId": "HC102826F0017",
  "recipientName": "LEIDOS, INC.",
  "recipientUei": "UE9QJD4KK1L6",
  "awardAmount": 41076977.72,
  "awardType": "DELIVERY ORDER",
  "description": "CYBER DEFENSE AND CYBERSECURITY SERVICES PROVIDER (CSSP) SUPPORT",
  "awardingAgency": "Department of Defense",
  "awardingSubAgency": "Defense Information Systems Agency",
  "startDate": "2026-03-14",
  "endDate": "2027-03-13",
  "recipientState": "VA",
  "placeOfPerformanceState": "PA",
  "naicsCode": "541513",
  "naicsDescription": "COMPUTER FACILITIES MANAGEMENT SERVICES",
  "pscCode": "DJ01",
  "extentCompeted": "FULL AND OPEN COMPETITION",
  "pricingType": "COST PLUS FIXED FEE",
  "potentialEndDate": "2031-03-13",
  "usaspendingUrl": "https://www.usaspending.gov/award/CONT_AWD_HC102826F0017_9700_HC102820D0001_9700"
}
```

Export as JSON, CSV, Excel or HTML table, or use the **Awards overview**, **Competition details** and **Top recipients** views in the Output tab.

### Limits and honest notes

- **`awardAmount` is the total amount obligated to date** for that award as reported by USAspending, not only the amount in your date range. With `dateType` set to anything other than "new awards", long-running older awards can appear with their lifetime totals.
- **Top recipients totals** add up the Award Amount of every award that matches your filters; they are an indicator of market share, not audited revenue.
- **Data freshness:** USAspending depends on agency reporting. Some contract data (notably Department of Defense) is published with a delay, and records can be corrected later.
- **Subcontracts are not included**; this covers prime awards.
- Keyword search is USAspending's own full-text search of award descriptions, so it only finds what agencies wrote in them.
- Recipient names are as reported by agencies; the same company can appear under several spellings or subsidiaries. Use `recipientUei` to group reliably.
- Not affiliated with or endorsed by USAspending.gov or the US Treasury. Verify important details on the linked USAspending page.

### Pricing

Currently free to run (you only pay normal Apify platform usage). Pricing may change to pay-per-result in the future; check the Store page.

### Support

Questions or feature requests: please open an issue in the Issues tab of this Actor.

# Actor input Schema

## `mode` (type: `string`):

'Awards' returns one row per award. 'Top recipients' ranks the recipients (competitors) by the total Award Amount of the awards that match your filters.

## `awardCategory` (type: `string`):

Contracts (definitive contracts, purchase orders, delivery orders, BPA calls), IDVs (IDIQ/GWAC/BPA/FSS vehicles), or grants (federal assistance grants and cooperative agreements).

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

Search award descriptions and related text. Several keywords are OR'd (any match). USAspending ignores keywords shorter than 3 characters.

## `recipientSearch` (type: `array`):

Competitor or company names, UEI numbers or DUNS. Matches recipient name/UEI/DUNS text, e.g. 'Booz Allen'.

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

2 to 6 digit NAICS codes; a shorter code includes everything beneath it (e.g. 5415 = computer systems design and related). Contracts and IDVs only.

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

Product/Service Codes, e.g. R408 or D399. Contracts and IDVs only.

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

Top-tier agency names or abbreviations, e.g. 'Department of Defense', 'DOD', 'GSA', 'HHS', 'NASA'. If none match, the run stops instead of searching everything.

## `awardingSubAgencies` (type: `array`):

Exact sub-agency names, e.g. 'Department of the Navy', 'Defense Logistics Agency', 'Centers for Disease Control and Prevention'.

## `recipientState` (type: `string`):

2-letter US state code of the recipient's location, e.g. VA.

## `placeOfPerformanceState` (type: `string`):

2-letter US state code where the work is performed, e.g. TX.

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

Start of the time period. Leave empty to use 'Look back N days'. Earliest supported date is 2007-10-01.

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

End of the time period. Leave empty for today.

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

Used when the start date is empty.

## `dateType` (type: `string`):

'New awards signed in the period' finds fresh wins (recommended for competitor and pipeline research). The other options match awards by their latest action, signing date or last-modified date, so long-running older awards can appear with their lifetime totals.

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

Only awards with an Award Amount at or above this.

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

Only awards with an Award Amount at or below this.

## `setAsideCodes` (type: `array`):

Contracts and IDVs only. Include awards with any of the selected set-aside types.

## `recipientTypes` (type: `array`):

Only awards to recipients with at least one of these business-type designations.

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

Look up specific awards. When given and no dates are set, the whole 2007-10-01 to today range is searched.

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

Used in 'Awards' output.

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

Descending shows the biggest or newest first.

## `includeDetails` (type: `boolean`):

Adds extent competed, number of offers, set-aside, pricing type, solicitation procedures, base-and-all-options value, potential end date and parent contract. Costs one extra API call per row, so runs are slower.

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

Maximum rows to return.

## Actor input object example

```json
{
  "mode": "awards",
  "awardCategory": "contracts",
  "keywords": [
    "cybersecurity"
  ],
  "daysBack": 365,
  "dateType": "new_awards_only",
  "sortBy": "amount",
  "order": "desc",
  "includeDetails": false,
  "maxItems": 100
}
```

# Actor output Schema

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

Dataset of matching awards with recipient, amount, awarding agency, dates, NAICS, award ID and a 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("utility-belt-labs/contract-awards-explorer").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("utility-belt-labs/contract-awards-explorer").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 utility-belt-labs/contract-awards-explorer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,utility-belt-labs/contract-awards-explorer"
        }
    }
}
```

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/jprOpqTdzQkAgYa3w/builds/FkAveDceWcGRgcLfj/openapi.json