# Federal Contracts Feed (`luxe_tasks/federal-contracts-feed`) Actor

U.S. federal contract awards from USAspending.gov as one normalized feed: agency, NAICS, PSC, set-aside filter, dates, amounts, place of performance, recipient. No contact persons stored. Price: $0.002/contract record + $0.005 start fee per run.

- **URL**: https://apify.com/luxe_tasks/federal-contracts-feed.md
- **Developed by:** [Luxe Tasks](https://apify.com/luxe_tasks) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 contract records

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

## Federal Contracts Feed

Developer: Luxe_tasks.

Get **U.S. federal contract awards from USAspending.gov** as one normalized feed: one row per award with the **agency, NAICS and
product/service (PSC) codes, award dates, award amounts, place of performance**, the recipient's business name and address where the
rules below allow it, and a link to the award on USAspending.gov.
It reads only the documented public USAspending.gov `spending_by_award` search API (no key needed).
This version reads USAspending.gov only; SAM.gov contract opportunities may come in a later version.
It is not affiliated with or endorsed by the U.S. Department of the Treasury or USAspending.gov.

### How to use it

1. Under **Sources**, keep `usaspending-awards` (contract awards, no key needed).
2. Optionally narrow the search with **Keywords**, **NAICS codes**, **Product/service codes**, **Set-aside**, **Agency**, the award date range and **Place of performance state**.
3. Run it. Records appear in the dataset (**Contract records** view), one row per record; the **SOURCE_STATUS** record in the key-value store
   (**Source status** in the run's Output tab) lists the source with its status and counts.

### How it reads the source

- USAspending.gov: `POST https://api.usaspending.gov/api/v2/search/spending_by_award/` (a search request with a JSON body; no key), contract award types A-D
  (BPA call, purchase order, delivery order, definitive contract), new awards whose base award date is in your range, sorted by award amount (largest first),
  100 awards per request and at most 100 requests (10,000 awards) per run (this Actor's limits).
- A record listed twice in a run is saved once.

### Input

- `sources` (required, exactly 1): `usaspending-awards`. Any other value stops the run before any request ("Invalid input"); only the $0.005 per-run start fee applies.
- `keywords` (optional, up to 20, at least 3 characters each); `naicsCodes` (optional, up to 50, 2-6 digits); `pscCodes` (optional, up to 50, 1-4 letters/digits).
- `setAside` (default `ANY`): one set-aside code such as `SBA`, `8A`, `WOSB`, `SDVOSBC`, `HZC`.
- `agency` (optional): awarding agency, the exact USAspending.gov top-tier name, for example "Department of Defense".
- `awardDateFrom` / `awardDateTo` (YYYY-MM-DD; default the last 30 days; not before 2007-10-01, a USAspending.gov search limit).
- `placeOfPerformanceState` (optional): two-letter U.S. state code.
- `maxResults` (default 100, 1-10,000): most records saved per source; each saved record is charged as one contract record ($0.002 per contract record), plus the $0.005 start fee per run. A record whose recipient data is withheld (see **Dun & Bradstreet data** below) has no contract-record charge; the $0.005 start fee per run still applies.
- `includeDescriptionSnippet` (default on): a plain-text snippet of the award description (at most 300 characters).
- `timeoutSecs` (default 60, 5-120): how long to wait for one API answer. `maxConcurrency` (fixed at 1).
- Unknown input fields are refused.

Each run has a default timeout of 1 hour (3600 seconds, this Actor's setting); for very large searches you can raise the timeout in the run options.
If the run is about to reach its timeout, the Actor stops starting new requests and lists the source as `time_limit_reached`; no contract-record event is charged for it (the $0.005 per-run start fee still applies).

### Output

- **Contract records** (dataset, `type: "record"`; the dataset holds record rows only): `source, recordId, awardNumber, awardType, agency, subAgency, fundingAgency, fundingSubAgency, naicsCode, naicsDescription, pscCode, pscDescription, awardDate, awardAmount, totalOutlays, startDate, endDate, lastModifiedDate, placeOfPerformanceCity, placeOfPerformanceState, placeOfPerformanceZip, placeOfPerformanceCountry, recipientName, recipientUei, recipientStreetAddress, recipientCity, recipientState, recipientCountyCode, recipientZip, recipientCountry, dnbOpenData, dnbAttribution, recipientWithheld, sourceAttribution, url, descriptionSnippet, sourceIndex, fetchedAt`. Fields USAspending.gov does not publish for an award are null.
- **Source status** (key-value store record `SOURCE_STATUS`, one JSON array): one entry per source: `index, url, source, status, requests, pages, recordsListed, recordsMatched, recordsSaved, chargeableRecords, duplicatesSkipped, recordsNotSavedBudget, dnbOpenDataRecords, recipientWithheldRecords, charged, chargedEvents, httpStatus, error, key`. `chargeableRecords` is the number of saved records charged as contract records (saved records minus `recipientWithheldRecords`); the $0.005 start fee per run is charged separately.
- **Records per source (JSON)** record (key-value store, `records-<index>-<host>-<hash>-json`): the same record rows as JSON, one record per source that was charged. A source whose saved records all have their recipient data withheld ends as `saved_without_charge` and has no such record; its rows are in the dataset.
- `RUN_SUMMARY` (key-value store): counts by status, charged `contract-record` events since the last start or resume, budget reached. Apify's billing is the official record.

Source statuses with no contract-record charge (the $0.005 per-run start fee still applies): `saved_without_charge`, `no_matching_records`, `blocked`, `rate_limited`, `skipped_blocked`, `server_error`, `fetch_failed`, `invalid_response`, `unexpected_redirect`, `api_rejected_request`, `http_error`, `response_too_large`, `robots_disallowed`, `budget_reached`, `time_limit_reached`.
A run whose only source ends as `saved_without_charge` finishes with the status message "Done: 0/1 succeeded" (no source was charged as a success; the $0.005 per-run start fee still applies); its rows are in the dataset and the run still succeeds.

### Limits

- Only USAspending.gov contract awards. Sub-awards, grants and loans are not offered.
- At most 10,000 awards per run (this Actor's limit); `maxResults` caps saved records; one API answer may be at most 30 MB (this Actor's limit).
- The description is a snippet only (at most 300 characters).
- No change tracking between runs in this version.
- If a run crashes or is restarted, each source's contract-record events are charged at most once (the $0.005 per-run start fee still applies), but the dataset and the charges can differ: a restarted run can deliver some record rows without their contract-record event, and if a run stops after a source was charged but before its rows were written and is not resumed, that source's records are only in its **Records per source (JSON)** record in the key-value store.

### Pricing

**Pricing: $0.002 per contract record, plus the $0.005 start fee per run. Both are pay-per-event prices in Apify Console.**

- Pay-per-event **`contract-record`**: $0.002 per contract record saved to the dataset, plus the $0.005 start fee per run; each record is charged at most once per run, after the source's records are saved.
- Records whose recipient data is withheld (`recipientWithheld` true, see **Dun & Bradstreet data**) are saved with no contract-record charge; the $0.005 start fee per run still applies.
- Records dated April 4, 2022 or later for which USAspending.gov publishes no recipient (all recipient fields null, `recipientWithheld` false) still carry the award facts and are charged as one contract record ($0.002 per contract record), plus the $0.005 start fee per run.
- Sources that deliver no record (statuses above) have no contract-record charge; the $0.005 per-run start fee still applies.
- A maximum total charge set on the run is respected: each chargeable record's event is reserved before it is saved, and when the budget is used up the remaining records are not saved (`recordsNotSavedBudget`) or the source shows `budget_reached`.
- **What you pay even when no record is charged:** the $0.005 start fee per run, charged by Apify through its synthetic `apify-actor-start` event ([Apify docs](https://docs.apify.com/platform/actors/publishing/monetize/pay-per-event#synthetic-start-event)). This Actor's memory is fixed at 1 GB (1024 MB), so the start fee is charged once per run.
- There is no per-source event: you pay $0.002 per contract record plus the $0.005 start fee per run. The synthetic `apify-default-dataset-item` event is not used (the Actor refuses to run if it is priced).

### Politeness and safety

- robots.txt of the API host is honoured for every request; `Crawl-delay` is respected. A robots.txt that returns 4xx (except 429) means no restrictions; a 429 is treated as a rate limit and stops the source; 5xx or an unreachable robots.txt means nothing is fetched from that host.
- At most about 1 request per second per host (this Actor's limit); fixed honest User-Agent `FederalContractsFeedActor/0.1.0 (+https://apify.com/luxe_tasks/federal-contracts-feed; honours robots.txt)`; no proxies, no evasion.
- Server errors (5xx) and network errors are retried twice per request (after 2 and 4 seconds, this Actor's setting). A 401 or 403, or a 429, stops the source for the rest of the run.
- Only the API host above is ever requested; private-network addresses are refused. No cookies, headers, logins or API keys can be supplied.

### Acceptable use

> By running this Actor you confirm that you will use the data lawfully and in line with the USAspending.gov terms; that you will not use
> the Actor to get around rate limits or any other access restriction; and that you will not use it to profile or contact individuals.

### Sharing your results

This Actor reads only USAspending.gov's public search API. USAspending.gov says its data "is available to copy, adapt, redistribute, or otherwise use for non-commercial or for commercial purposes, subject to the Limitation on Permissible Use of Dun & Bradstreet, Inc. Data noted on the homepage" (see https://www.usaspending.gov/db_info). If you publish or redistribute results, keep each row's `sourceAttribution` (for example "USAspending.gov, U.S. Department of Treasury, Bureau of the Fiscal Service"), do not add Dun & Bradstreet data from other sources, and do not present the data as official or as endorsed by the U.S. Department of the Treasury or USAspending.gov. You are responsible for how you use and share the results.

### Privacy

This Actor stores contract facts only: it saves no point-of-contact data. Person contact fields (name, e-mail, phone, fax, title) are never requested or stored, and the description snippet has sentences that mention a contact removed, with e-mail addresses, phone numbers and web links that the Actor detects removed from it and from the other text fields. Detection is pattern-based and cannot catch every case. Recipient data is limited to business name, address fields and UEI (see the next section); DUNS numbers are never requested or stored.

> "Results are written only to your run's default Apify storage. The developer does not copy, view or retain them. If your results contain
> personal data, you are the controller and the developer acts only as your processor under Apify's Standard Actor Contract. Apify's retention settings apply."

### Data sources and attribution

- Every row: `sourceAttribution` "USAspending.gov, U.S. Department of Treasury, Bureau of the Fiscal Service".
- **Dun & Bradstreet data.** Recipient data in records dated before April 4, 2022 (or with no date) may come from Dun & Bradstreet, whose terms restrict its use, so for those records the Actor leaves every recipient field (`recipientName`, the address fields and `recipientUei`) empty and sets `recipientWithheld` to true; each such record is still saved, with no contract-record charge, and the $0.005 start fee per run still applies. To avoid them, set `awardDateFrom` to 2022-04-04 or later.
- `dnbOpenData` is always false and `dnbAttribution` always null in this version.
- Records from April 4, 2022 on carry the recipient's business name, address and UEI as published by USAspending.gov.

### Third-party software

Runtime dependencies (apify, robots-parser, tldts) are listed in NOTICE with their licences.

### Runtime

Node 24 (`engines`, `.nvmrc`, Dockerfile `apify/actor-node:24`). Memory: fixed at 1024 MB (the work is network-bound and rate-limited to about 1 request per second per host). Tests: `npm test`; end-to-end: `sh scripts/e2e-netns.sh` (local mock API only).

Contact: https://apify.com/luxe_tasks · Issues tab on the actor page.

# Actor input Schema

## `sources` (type: `array`):

The public API to read: usaspending-awards (USAspending.gov contract awards, no key needed). This version reads USAspending.gov only.

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

USAspending.gov keyword search (awards matching any keyword). At least 3 characters each.

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

2 to 6 digit NAICS codes, e.g. 541511. Empty = all.

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

PSC codes, e.g. DA10. Empty = all.

## `setAside` (type: `string`):

One set-aside code, e.g. SBA (total small business), 8A, WOSB, SDVOSBC, HZC. ANY = no set-aside filter.

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

Awarding agency name: the exact USAspending.gov top-tier name, e.g. "Department of Defense".

## `awardDateFrom` (type: `string`):

New awards whose base award date is on or after this date. Empty = 30 days ago. Not before 2007-10-01.

## `awardDateTo` (type: `string`):

New awards whose base award date is on or before this date. Empty = today.

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

Two-letter US state code, e.g. VA.

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

At most this many matching records are saved per source; each is charged as one contract record, plus the $0.005 start fee per run. A record whose recipient data is withheld (Dun & Bradstreet rule) is saved with no contract-record charge; the $0.005 start fee per run still applies.

## `includeDescriptionSnippet` (type: `boolean`):

A plain-text snippet of the award description, at most 300 characters (contact sentences and detected e-mail addresses, phone numbers and links removed).

## `timeoutSecs` (type: `integer`):

How long to wait for one API answer.

## `maxConcurrency` (type: `integer`):

Items processed in parallel (each site still gets at most 1 request per second).

## Actor input object example

```json
{
  "sources": [
    "usaspending-awards"
  ],
  "keywords": [],
  "naicsCodes": [],
  "pscCodes": [],
  "setAside": "ANY",
  "agency": "",
  "awardDateFrom": "",
  "awardDateTo": "",
  "placeOfPerformanceState": "",
  "maxResults": 100,
  "includeDescriptionSnippet": true,
  "timeoutSecs": 60,
  "maxConcurrency": 1
}
```

# Actor output Schema

## `records` (type: `string`):

Default dataset, 'Contract records' view: one row per saved record: source, recordId, awardNumber, awardType, agency, subAgency, fundingAgency, fundingSubAgency, naicsCode, naicsDescription, pscCode, pscDescription, awardDate, awardAmount, totalOutlays, startDate, endDate, lastModifiedDate, placeOfPerformanceCity, placeOfPerformanceState, placeOfPerformanceZip, placeOfPerformanceCountry, recipientName, recipientUei, recipientStreetAddress, recipientCity, recipientState, recipientCountyCode, recipientZip, recipientCountry, dnbOpenData, dnbAttribution, recipientWithheld, sourceAttribution, url, descriptionSnippet, sourceIndex, fetchedAt. The dataset holds record rows only.

## `sources` (type: `string`):

SOURCE_STATUS record (default key-value store): one JSON array with one entry per input source: index, url, source, status, requests, pages, recordsListed, recordsMatched, recordsSaved, chargeableRecords, duplicatesSkipped, recordsNotSavedBudget, dnbOpenDataRecords, recipientWithheldRecords, charged, chargedEvents, httpStatus, error, key.

## `sourceFiles` (type: `string`):

Default key-value store, records starting with 'records-': one JSON record per source that was charged ({source, sourceIndex, fetchedAt, recordCount, records}), the same record rows as in the dataset. A source whose saved records all have their recipient data withheld has no such record (its rows are in the dataset).

## `runSummary` (type: `string`):

RUN_SUMMARY record: totals by status, charged contract-record events since the last start or resume, budget reached and stopped domains.

# 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 = {
    "sources": [
        "usaspending-awards"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("luxe_tasks/federal-contracts-feed").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 = { "sources": ["usaspending-awards"] }

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

```

## MCP server setup

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

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/boUtQDUzIAuHurMha/builds/JeGbVlXzRT06fbXIn/openapi.json