# Federal Contract Award Finder (`hereditary_model/federal-contract-finder`) Actor

Finds recently awarded US federal contracts matching your keywords or NAICS codes, with the winning company, amount, and agency, from USAspending.gov's public data.

- **URL**: https://apify.com/hereditary\_model/federal-contract-finder.md
- **Developed by:** [Aaron Marxsen](https://apify.com/hereditary_model) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 contract award returneds

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

## Federal Contract Award Finder

Every federal contract award becomes public record on USAspending.gov within days of signing — who won it, for how much, from which agency, doing what. Most of it is buried in a search UI built for policy analysts, not for a small business owner trying to figure out who to team with or which agencies actually spend money in their category. This turns it into a ranked, exportable lead list.

### What it is (and isn't)

This finds contracts that have **already been awarded** — it's market and competitive intelligence, not a bid-opportunity feed. Use it to answer: who's winning work like mine, which agencies spend in this category, and who might take me on as a subcontractor. If you want open solicitations to bid on directly, that's SAM.gov's opportunities database, a separate system with its own free API key.

### What it does

1. Searches USAspending.gov's public award data for each of your keywords, restricted to actual contracts (not grants or loans).
2. Optionally narrows to specific NAICS codes and a date range.
3. Sorts by award size, largest first, so the contracts worth knowing about surface first.
4. Ranks the most frequent winning recipients per keyword — your competitors, or your future teaming partners.
5. Drops anything under your minimum award size **before** billing.

### Output

| Field | Notes |
| --- | --- |
| `keyword`, `recipientName`, `awardAmount` | The award itself |
| `awardingAgency`, `awardingSubAgency` | Who bought it |
| `startDate`, `endDate`, `description` | Period of performance and scope |
| `naicsCode`, `naicsDescription`, `placeOfPerformanceState` | Classification and location |
| `keywordTotalAwards`, `keywordTotalValue`, `keywordTopRecipients` | Rollup for this keyword, repeated on every row |

### Input

Only `keywords` is required.

```json
{
  "keywords": ["electrical contracting"],
  "naicsCodes": [],
  "startDate": "2025-01-01",
  "minAwardAmount": 25000
}
```

### Pricing

Pay per event. You're billed per award returned and once per keyword digested, not for the underlying query. Data source: USAspending.gov, no API key required.

# Actor input Schema

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

Search terms describing the work, one per line, for example "electrical contracting" or "IT support services".

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

Optional. Narrow results to these NAICS codes, for example 238210.

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

YYYY-MM-DD. Only include contracts awarded on or after this date.

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

YYYY-MM-DD. Defaults to today if left blank.

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

Drop awards worth less than this, before billing.

## `maxResultsPerKeyword` (type: `integer`):

Caps how many awards are fetched per keyword, sorted by award amount, largest first.

## Actor input object example

```json
{
  "keywords": [
    "electrical contracting"
  ],
  "naicsCodes": [],
  "startDate": "",
  "endDate": "",
  "minAwardAmount": 0,
  "maxResultsPerKeyword": 50
}
```

# Actor output Schema

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

No description

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

No description

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

// Run the Actor and wait for it to finish
const run = await client.actor("hereditary_model/federal-contract-finder").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": ["electrical contracting"] }

# Run the Actor and wait for it to finish
run = client.actor("hereditary_model/federal-contract-finder").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": [
    "electrical contracting"
  ]
}' |
apify call hereditary_model/federal-contract-finder --silent --output-dataset

```

## MCP server setup

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

```

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/VWkhrO4zLbfxEL9Lq/builds/BJeA8tWwUX9Embrjp/openapi.json