# Federal Contract Awards - USAspending, Expiring Contracts (`optimistical_lectern/federal-contract-vendor-enricher`) Actor

Search U.S. federal contract awards on USAspending.gov by keyword, NAICS code, contractor or agency. Get the contractor, address, amount, agency, NAICS, PSC, dates and days until the contract ends, and find contracts ending soon. No API key needed; optional SAM.gov enrichment.

- **URL**: https://apify.com/optimistical_lectern/federal-contract-vendor-enricher.md
- **Developed by:** [Ivan Honer](https://apify.com/optimistical_lectern) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.25 / 1,000 contracts

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

## 🏛️ Federal Contract Awards: USAspending, Expiring Contracts

Search **U.S. federal contract awards** from USAspending.gov by keyword, NAICS code, contractor or agency, and get clean rows with the **contractor, their address, the amount, the agency, NAICS and PSC codes, start and end dates, and how many days are left**. Find the **contracts ending soon**, the ones most likely to be recompeted.

- ✅ **No API key needed**: uses the official USAspending.gov API
- ✅ **"Ending soon" mode**: running contracts that end within the next N days, soonest first
- ✅ **Contractor address** (city, state, ZIP) on every row
- ✅ **NAICS and PSC codes with descriptions**, awarding and funding agency
- ✅ **Scope tags** from the description: cybersecurity, AI/ML, cloud/DevSecOps, data, software, help desk
- ✅ **Optional SAM.gov enrichment**: CAGE code, website, registration status and business types

### What does it do?

1. Searches USAspending.gov for contract awards (definitive contracts, purchase orders, delivery orders and BPA calls) that match your keywords, NAICS codes, contractors and agencies, with activity in your date range.
2. Works out whether each contract is still running and how many days are left.
3. In **ending soon** mode, reads contracts in end-date order and keeps the running ones that end within your window.
4. Optionally looks up each contractor in SAM.gov with your own free API key.

### Use cases

- 🎯 **Capture and business development.** Find contracts in your NAICS codes that end in the next six months, and who holds them.
- 🤝 **Teaming and subcontracting.** Find the primes winning work in your niche, with their addresses.
- 📈 **Market research.** Who wins what, from which agencies, for how much.
- 💼 **B2B sales to government contractors.** A list of active federal contractors in a field, by state.
- 🤖 **AI agents.** "Which zero-trust contracts at DHS end before June?"

### What data can you get?

| Field | What it is |
|---|---|
| `awardId`, `contractType`, `awardUrl` | The award ID (PIID), type (e.g. `DELIVERY ORDER`) and its USAspending page |
| `recipientName`, `recipientUei` | The contractor and its Unique Entity ID |
| `recipientAddress`, `recipientCity`, `recipientState`, `recipientZip`, `recipientCountry` | Where the contractor is registered |
| `awardAmount`, `totalOutlays` | Total obligated amount and outlays so far (USD) |
| `awardingAgency`, `awardingSubAgency`, `fundingAgency` | Who awarded and who pays |
| `naicsCode`, `naicsDescription`, `pscCode`, `pscDescription` | Industry and product/service codes |
| `placeOfPerformanceCity`, `placeOfPerformanceState`, `placeOfPerformanceCountry` | Where the work is done |
| `startDate`, `endDate`, `daysUntilEnd`, `contractStatus` | Period of performance, days left, and `active` or `ended` |
| `description`, `scopeTags` | The award description and the scope tags found in it |
| `lastModified` | When USAspending last updated the award |
| `cageCode`, `vendorWebsite`, `samRegistrationStatus`, `samRegistrationExpires`, `businessTypes` | From SAM.gov, only when you give a SAM.gov API key |

### How to use it

1. Click **Try for free** (or **Start**) at the top of this page.
2. Enter **Keywords**, **NAICS codes**, **Contractor names** or **Awarding agencies**. At least one is needed.
3. Choose **Contracts to include**: everything, only running contracts, or only those ending soon.
4. Optionally set a **Minimum award amount** and the **Activity** date range.
5. Press **Start**, then download the results from the **Output** tab as Excel, CSV or JSON.

### Input examples

**Cybersecurity contracts in IT services NAICS codes ending in the next 6 months.**

```json
{
  "keywords": ["cybersecurity"],
  "naicsCodes": ["541512", "541519"],
  "minAwardAmount": 1000000,
  "contractStatus": "ending",
  "endingWithinDays": 180
}
```

**Everything a competitor is running at one agency.**

```json
{
  "vendorNames": ["Leidos"],
  "awardingAgencies": ["Department of Homeland Security"],
  "contractStatus": "active"
}
```

**A whole NAICS family, by keyword, over two years.**

```json
{
  "naicsCodes": ["5415"],
  "keywords": ["help desk"],
  "startDate": "2024-10-01",
  "maxResults": 1000
}
```

### Output example

```json
{
  "awardId": "FA822226FB007",
  "recipientName": "CYKOR LLC",
  "recipientUei": "...",
  "recipientCity": "ANNAPOLIS",
  "recipientState": "MD",
  "awardAmount": 6884161.01,
  "awardingAgency": "Department of Defense",
  "naicsCode": "541519",
  "pscCode": "7B20",
  "startDate": "...",
  "endDate": "2026-12-18",
  "daysUntilEnd": 64,
  "contractStatus": "active",
  "scopeTags": ["Cybersecurity"],
  "awardUrl": "https://www.usaspending.gov/award/CONT_AWD_..."
}
```

### Statuses and errors

| Situation | What happens | Charged? |
|---|---|---|
| Matching contract | Saved as one row | Yes |
| Contract filtered out by **Contracts to include** | Read but not saved | No |
| No search terms given | Run stops: "Add at least one keyword, NAICS code, vendor name or agency" | No |
| Keyword shorter than 3 characters, or a NAICS code that is not 2 to 6 digits | Run stops and names the bad value | No |
| USAspending is unavailable | Retried, then the run stops with USAspending's message | No |
| SAM.gov key rejected or daily limit reached | A warning in the log; the remaining contracts are saved without SAM.gov data | Only the contracts |
| More than 6,000 awards read without filling the request | The run stops and says so; narrow the search | Only what was saved |

### How much does it cost?

You pay per contract saved. Contracts that are read and filtered out are free. Platform usage is included.

| Contracts | Price on the Free and Bronze tiers |
|---|---|
| 100 | $0.30 |
| 1,000 | $3.00 |
| 10,000 | $30.00 |

### FAQ

#### Where does the data come from?

USAspending.gov, the official source for U.S. federal spending, run by the Department of the Treasury. Award data there comes from FPDS and agency reporting, usually within days of an action. Contract ceilings and option periods are not part of this search; `endDate` is the current end of the period of performance.

#### Does "ending soon" mean it will be recompeted?

Not always. Options can be exercised, contracts can be extended, and some work is not re-solicited. A contract ending soon is a lead to research, not a guarantee.

#### Do I need a SAM.gov API key?

No. Everything except the SAM.gov fields works without one. To add CAGE codes, websites and business types, request a free public API key in your SAM.gov account settings. Personal keys allow a limited number of lookups a day, so the Actor caches each contractor and stops asking once the limit is reached.

#### Can I use it through the API or from an AI agent?

Yes. Call it like any Apify Actor:

```bash
curl -X POST "https://api.apify.com/v2/acts/optimistical_lectern~federal-contract-vendor-enricher/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["zero trust"], "contractStatus": "ending", "endingWithinDays": 180}'
```

From Python: `ApifyClient("YOUR_APIFY_TOKEN").actor("optimistical_lectern/federal-contract-vendor-enricher").call(run_input={...})`. AI agents can use it through Apify's MCP server at `mcp.apify.com`. It runs with limited permissions, so it needs no approval step.

#### Can I run it every week?

Yes. Create a schedule in Apify Console and send new results to Google Sheets, Slack or a webhook with an integration.

#### Something looks wrong?

Open an issue on the **Issues** tab with your input. Every report is read.

# Actor input Schema

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

Words in the award description, e.g. 'zero trust', 'cybersecurity', 'help desk'. At least 3 characters each.

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

2 to 6 digits, e.g. 541512 (computer systems design) or 5415 (all computer services).

## `vendorNames` (type: `array`):

Only awards to these contractors, e.g. 'Leidos', 'Booz Allen'.

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

Top-level agency names as USAspending writes them, e.g. 'Department of Defense', 'Department of Homeland Security'.

## `minAwardAmount` (type: `integer`):

Skip smaller awards. Leave empty for no minimum.

## `contractStatus` (type: `string`):

"Ending soon" returns running contracts that end within the number of days below, soonest first: the ones likely to be recompeted.

## `endingWithinDays` (type: `integer`):

Used with "Only contracts ending soon".

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

Awards with an action (new award or modification) on or after this date. Defaults to one year ago. Earliest is 2007-10-01.

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

Defaults to today.

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

Stop after saving this many.

## `samGovApiKey` (type: `string`):

Your free SAM.gov public API key. Adds CAGE code, website, registration status and business types for each contractor. Personal keys allow a limited number of lookups a day; once used up, results continue without SAM.gov data.

## Actor input object example

```json
{
  "keywords": [
    "zero trust"
  ],
  "minAwardAmount": 500000,
  "contractStatus": "ending",
  "endingWithinDays": 180,
  "maxResults": 100
}
```

# Actor output Schema

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

One item per contract award.

# 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": [
        "zero trust"
    ],
    "minAwardAmount": 500000,
    "contractStatus": "ending"
};

// Run the Actor and wait for it to finish
const run = await client.actor("optimistical_lectern/federal-contract-vendor-enricher").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": ["zero trust"],
    "minAwardAmount": 500000,
    "contractStatus": "ending",
}

# Run the Actor and wait for it to finish
run = client.actor("optimistical_lectern/federal-contract-vendor-enricher").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": [
    "zero trust"
  ],
  "minAwardAmount": 500000,
  "contractStatus": "ending"
}' |
apify call optimistical_lectern/federal-contract-vendor-enricher --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,optimistical_lectern/federal-contract-vendor-enricher"
        }
    }
}
```

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/GQqEJC493IJnoWUdO/builds/1gduJforYBUvNfEbh/openapi.json