# US Federal Contracts Scraper (`trovevault/federal-contracts-scraper`) Actor

Search US federal contract awards by keyword, agency, recipient, NAICS code, and date. Export award values, recipients, agencies, and performance details.

- **URL**: https://apify.com/trovevault/federal-contracts-scraper.md
- **Developed by:** [Trove Vault](https://apify.com/trovevault) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.85 / 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?

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

## US Federal Contracts Scraper

Extract structured US federal contract award records from USAspending.gov. Search by keywords, recipient, awarding agency, NAICS code and date range, then download rows with award IDs, recipients, amounts, descriptions, agencies, dates, procurement classifications and public record URLs.

This is a source scraper. It preserves the fields reported by USAspending and does not claim that a contract is open for bids, available for subcontracting or newly created unless the selected date filter supports that interpretation. Use `newAwardsOnly` when you need awards whose base transaction falls inside the period; an ordinary action-date search can return modifications to older awards.

### Who uses this Actor?

- GovCon research teams export a focused award sample for analysis.
- Business-development teams search historical awards by service, agency or NAICS code.
- Analysts build a dated recipient or agency dataset for internal reporting.
- Other Actors consume the normalized rows through an Apify dataset.

### How do I run it?

```json
{
  "keywords": ["cybersecurity"],
  "startDate": "2026-06-01",
  "endDate": "2026-09-05",
  "newAwardsOnly": true,
  "maxResults": 3
}
```

`startDate` and `endDate` are required. The endpoint supports data from 1 October 2007 onward and this Actor limits one search to 366 days. Results are sorted by award amount descending. `maxResults` accepts 1–1000 rows.

### What input can I use?

| Field | Description |
| --- | --- |
| `keywords` | Optional award-description terms, up to 10. Example: `cybersecurity`. |
| `recipientSearchText` | Optional recipient name text. |
| `naicsCodes` | Optional NAICS codes, up to 25. |
| `agencies` | Optional top-tier awarding agency names, up to 25. |
| `startDate`, `endDate` | Required inclusive date range in `YYYY-MM-DD`. |
| `newAwardsOnly` | Uses the base transaction date so the period focuses on newly established awards. |
| `dateType` | `action_date`, `date_signed`, `last_modified_date` or `new_awards_only`; default is `action_date`. |
| `awardTypeCodes` | USAspending codes; default `A`, `B`, `C`, `D` selects procurement contracts. |
| `maxResults` | Rows returned, 1–1000; default 100. |
| `datasetId` | Optional Apify dataset to append the same rows to. |
| `runId` | Optional client or pipeline reference copied to each row. |

Set `newAwardsOnly: true` for base-transaction filtering; it takes precedence over `dateType` because the Apify form may supply the date-type default automatically. Inputs are validated before the upstream request. Invalid input fails with a clear message in `RUN_SUMMARY`.

### What data does the Actor return?

One row is written per award returned by the source. A typical row looks like:

```json
{
  "awardId": "47QFCA26F0024",
  "recipientName": "GENERAL DYNAMICS INFORMATION TECHNOLOGY, INC.",
  "awardAmount": 19613720.41,
  "description": "ENTERPRISE NETWORK OPERATIONS AND CYBERSECURITY SUPPORT ENOCS",
  "awardingAgency": "General Services Administration",
  "startDate": "2026-06-29",
  "endDate": "2027-06-30",
  "awardDateSigned": "2026-06-29",
  "naicsCode": "541512",
  "naicsDescription": "Computer Systems Design Services",
  "sourceRecordUrl": "https://www.usaspending.gov/award/CONT_AWD_47QFCA26F0024_4732_47QTCK18D0003_4732"
}
```

The dataset also includes recipient identifiers, funding agency, award type, PSC fields, place-of-performance codes, contract award type, set-aside type and extent competed when the source supplies them. Missing source fields are omitted from a row. `RUN_SUMMARY` records result count, pagination and source messages.

### How can I integrate it?

```bash
curl --request POST \
  'https://api.apify.com/v2/acts/trovevault~federal-contracts-scraper/run-sync-get-dataset-items' \
  --header "Authorization: Bearer ${APIFY_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"keywords":["cybersecurity"],"startDate":"2026-06-01","endDate":"2026-09-05","newAwardsOnly":true,"maxResults":3}'
```

### What are the source limits?

The Actor uses the public USAspending API over HTTPS and does not require an API key. Search fields and date semantics follow USAspending's API contract. The site's own documentation warns that data availability and reporting timing vary by agency; Department of Defense procurement data may be delayed. An award record is not a solicitation and does not indicate that the recipient is seeking partners.

The `new_awards_only` date type refers to a base transaction, while `action_date` commonly refers to the latest transaction. This distinction matters when a recent modification belongs to an older contract. Always inspect `awardDateSigned`, `startDate`, `endDate` and the description before making a commercial or compliance decision.

The Actor performs one bounded API request and does not crawl award attachments, SAM.gov notices, private systems or login-protected pages. USAspending can return a `hasNextPage` indication when more rows match than `maxResults`; rerun with a narrower filter or use pagination in a downstream workflow.

### How do I troubleshoot a run?

| Issue | Likely cause | What to do |
| --- | --- | --- |
| No awards are returned | The filters are too narrow or the agency has not reported matching data | Broaden the date range or remove one optional filter, then retry. |
| A recent search includes an older award | `action_date` can select a recent modification to an existing award | Enable `newAwardsOnly` when you need newly established awards. |
| Fewer rows appear than the source reports | USAspending can repeat the same award across result records | The Actor removes duplicate award records; inspect `duplicateCount` in `RUN_SUMMARY`. |
| The upstream request fails | USAspending may be temporarily unavailable or rate-limiting requests | Retry later; the error remains available in `RUN_SUMMARY`. |

### Frequently asked questions

**Does it find open opportunities?** No. It extracts awards already recorded by USAspending. Use an opportunities source for solicitations and deadlines.

**Does it include grants?** The default award codes select contracts. Change `awardTypeCodes` only when you intentionally need other USAspending award types.

**Can I schedule it?** Yes. Use an Apify Schedule with a rolling date range and a `runId` to identify each collection. The Actor does not create its own schedule.

**Can I append to an existing dataset?** Yes, provide `datasetId` and ensure the running account can write to that dataset. The default dataset is populated as well.

For a suspected source or normalization issue, open an Actor issue with sanitized input, the award ID and the observed field. Do not include tokens or confidential information.

### Changelog

- **0.1.0:** USAspending contract award extraction with keyword, recipient, agency, NAICS, date and award-type filters; normalized procurement fields; dataset and workflow integration.

# Actor input Schema

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

Optional award-description search terms, such as cybersecurity or laboratory equipment. Up to 10 terms.

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

Optional recipient company or organization name. USAspending performs a text search across recipient records.

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

Optional NAICS industry codes, for example 541512 for computer systems design. Up to 25 codes.

## `agencies` (type: `array`):

Optional top-tier awarding agency names, such as Department of Veterans Affairs. Up to 25 names.

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

Required beginning of the inclusive search period. USAspending search endpoints cover 2007-10-01 onward.

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

Required end of the inclusive search period. The range may cover at most 366 days.

## `newAwardsOnly` (type: `boolean`):

When true, use the award base transaction date so results focus on awards first established in the period. This can exclude later modifications to older awards.

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

Date used by USAspending: action date (latest transaction), signed date, last modified date, or new award base transaction date. Usually leave the default.

## `awardTypeCodes` (type: `array`):

Optional USAspending award codes. The default selects procurement contracts; change only when you intentionally need other award types.

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

Maximum rows returned in this run. Larger values increase output size and API work.

## `datasetId` (type: `string`):

Optional Apify dataset ID. Matching rows are appended there and also written to this run's default dataset.

## `runId` (type: `string`):

Optional client or pipeline reference copied to each row, for example govcon-search-2026-09.

## Actor input object example

```json
{
  "keywords": [
    "cybersecurity"
  ],
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "newAwardsOnly": true,
  "dateType": "action_date",
  "awardTypeCodes": [
    "A",
    "B",
    "C",
    "D"
  ],
  "maxResults": 3
}
```

# Actor output Schema

## `dataset` (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": [
        "cybersecurity"
    ],
    "startDate": "2026-01-01",
    "endDate": "2026-01-31",
    "newAwardsOnly": true,
    "maxResults": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("trovevault/federal-contracts-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 = {
    "keywords": ["cybersecurity"],
    "startDate": "2026-01-01",
    "endDate": "2026-01-31",
    "newAwardsOnly": True,
    "maxResults": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("trovevault/federal-contracts-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 '{
  "keywords": [
    "cybersecurity"
  ],
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "newAwardsOnly": true,
  "maxResults": 3
}' |
apify call trovevault/federal-contracts-scraper --silent --output-dataset

```

## MCP server setup

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