# USAspending Federal Awards Monitor (Contracts & Grants) (`brightish_ascent/usaspending-awards-monitor`) Actor

Unofficial; not affiliated with USAspending.gov or Treasury. Search and monitor U.S. federal contract, IDV and grant awards via the official USAspending API. Filter by keyword, recipient, agency, NAICS, assistance listing, state, amount. Only-new results plus amount changes.

- **URL**: https://apify.com/brightish_ascent/usaspending-awards-monitor.md
- **Developed by:** [Michael Rice](https://apify.com/brightish_ascent) (community)
- **Categories:** Business, Developer tools, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 federal award rows

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

## USAspending Federal Awards Monitor (Contracts & Grants)

**Unofficial.** Not affiliated with or endorsed by USAspending.gov, the U.S. Department of the Treasury (Bureau of the Fiscal Service) or any federal agency. Data comes from the official [USAspending.gov API](https://api.usaspending.gov/). Per [USAspending's licensing statement](https://www.usaspending.gov/about), the data may be used for commercial purposes, subject to the [Limitation on Permissible Use of Dun & Bradstreet, Inc. Data](https://www.usaspending.gov/db_info). Recipient names may include D\&B Open Data (source: Dun & Bradstreet).

Citation: USAspending.gov, U.S. Department of Treasury, Bureau of the Fiscal Service, https://www.usaspending.gov.

Search U.S. federal **contracts**, **IDVs** and **grants**, newest-modified first. Put it on a schedule with **Only new or changed since last run** to get awards you haven't seen, plus awards whose amount, outlays or end date changed.

### What you get

One row per prime award: award ID, category and type, recipient name and UEI, award amount, total outlays, description, last modified time, base obligation / start / end dates, awarding agency and sub-agency, funding agency, NAICS and PSC (contracts/IDVs), assistance listings (grants), place-of-performance state and country, disaster/emergency (DEF) codes, and the USAspending award page link.
Rows also carry `updateType` (`new` / `changed` in monitor mode, otherwise `null`), `previous` (on changed rows: the earlier award amount, total outlays, end date and last-modified time) and `changeHash`. Recipient street addresses and DUNS numbers are not included. `lastModified` is shown as published by USAspending (YYYY-MM-DDTHH:MM:SS); the API does not state a time zone.

### Input

| Field | Notes |
|---|---|
| awardCategories | contracts, idvs, grants (default contracts + grants) |
| keywords | each 3-100 characters |
| recipientSearch | recipient name or UEI |
| awardingAgencies | top-tier names or abbreviations (DOD, NASA, NSF…); unknown names fail clearly |
| naicsCodes | contracts/IDVs only |
| assistanceListings | grants only, e.g. 47.084 |
| placeOfPerformanceStates | 2-letter codes |
| minAmount / maxAmount | award amount range (USD) |
| dateType, fromDate, toDate | last_modified_date (default) or action_date; with no dates, the last 7 days |
| maxItems | default 25, max 1000 per run |
| onlyNewSinceLastRun | monitor mode, see below |
| outputFormat | full or compact |

Example: new or changed DoD cybersecurity contracts in Virginia:

```json
{ "awardCategories": ["contracts"], "keywords": ["cybersecurity"], "awardingAgencies": ["DOD"], "placeOfPerformanceStates": ["VA"], "onlyNewSinceLastRun": true }
```

### Only new or changed since last run

The first run with a set of filters is a baseline; it saves state in a named key-value store in **your** Apify account (`usaspending-awards-monitor-state`). Later runs with the same filters look at awards modified since the day before the last complete run and return:

- `new`: awards not delivered before;
- `changed`: delivered awards whose award amount, total outlays or end date changed (with `previous` values).

Modifications that change none of these three fields (for example description or metadata edits) are not re-sent. Changed rows are charged like any other row. If a run is cut short (maxItems, your cost limit or the request cap), the rest arrive on the next run. If a baseline is cut short, older matches are only delivered later if they are modified again (`olderMatchesSkipped: true`). Up to 50,000 delivered awards are remembered per filter set (most recently modified kept); an award forgotten beyond that would show up as `new` again.

### Run summary

The `OUTPUT` record lists `count`, `chargedCount`, the dates and request bodies used, `truncated` (true only when more matching rows exist beyond `maxItems`, the cost limit or the request cap), and monitor details (`newCount` and `changedCount` counted from pushed rows, `skippedUnchanged`, cursor). The output schema lists every field.

### Limits and notes

- Not legal, financial or procurement advice; verify on USAspending.gov / SAM.gov.
- No API key. The Actor waits at least 250 ms between requests (retries included) and makes at most 40 requests per run (100 rows per page). Max 1,000 rows per run: this is a search and monitoring tool, not a bulk export (use USAspending's own download tools for bulk data).
- USAspending's search covers awards from 2007-10-01 on. Data is reported by agencies and can be revised; amounts are as published.
- Very broad monitors (for example all contracts, no other filters) can see more modifications per day than one run reads (40 requests x 100 rows). Then every run hits the request cap, the cursor does not advance and older-modified awards may never be reached; the run summary shows `consecutiveCappedRuns` and logs a warning from the second capped run. Narrow the filters or split into several monitors. If the cap is hit, `categoriesPartial` / `categoriesSkipped` name the award categories that were cut or not queried that run.
- `minAmount` / `maxAmount` filter on the current award amount. If a deobligation (or increase) moves an award outside that range, it stops matching, so no `changed` row is sent for that change.
- Subawards, loans and direct payments are not included.

### Support

Questions or problems: digitalpromohub.support@gmail.com

# Actor input Schema

## `awardCategories` (type: `array`):

contracts = definitive contracts, purchase orders, delivery/task orders, BPA calls; idvs = indefinite delivery vehicles (GWACs, IDIQs, BPAs, FSS); grants = block, formula, project grants and cooperative agreements. Default: contracts and grants.

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

Award keyword search (each 3-100 characters), e.g. cybersecurity. Matches USAspending's keyword index (description, recipient, ids and more).

## `recipientSearch` (type: `string`):

Recipient name text or 12-character UEI (at least 3 characters).

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

Top-tier agency names or abbreviations, e.g. Department of Defense, DOD, NASA, NSF. Unknown names fail the run with a clear message.

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

2-6 digit NAICS codes, e.g. 541512. Applies to contracts and IDVs only.

## `assistanceListings` (type: `array`):

Assistance Listing (CFDA) numbers, e.g. 47.084. Applies to grants only.

## `placeOfPerformanceStates` (type: `array`):

2-letter U.S. state codes, e.g. CO, VA.

## `minAmount` (type: `number`):

Lower bound on the award amount (obligated total).

## `maxAmount` (type: `number`):

Upper bound on the award amount.

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

Which date fromDate/toDate filter on. Monitor mode requires last_modified_date.

## `fromDate` (type: `string`):

YYYY-MM-DD, on or after 2007-10-01. If fromDate and toDate are empty, the last 7 days are used.

## `toDate` (type: `string`):

YYYY-MM-DD. Default: tomorrow (UTC).

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

Maximum rows per run (you pay per row). Default 25, max 1000.

## `onlyNewSinceLastRun` (type: `boolean`):

For schedules: return awards not delivered before with the same filters, plus delivered awards whose award amount, total outlays or end date changed (updateType "changed", with previous values). First run is a baseline.

## `outputFormat` (type: `string`):

compact = key fields only, description cut to 300 characters.

## Actor input object example

```json
{
  "awardCategories": [
    "contracts",
    "grants"
  ],
  "keywords": [
    "cybersecurity"
  ],
  "dateType": "last_modified_date",
  "maxItems": 20,
  "onlyNewSinceLastRun": false,
  "outputFormat": "full"
}
```

# Actor output Schema

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

Default dataset. full rows: awardKey, awardId, category, awardType, recipientName, recipientUei, awardAmount, totalOutlays, description, lastModified (as published by USAspending, no time zone stated), baseObligationDate, startDate, endDate, awardingAgency, awardingSubAgency, fundingAgency, naics, psc, assistanceListings, placeOfPerformanceState, placeOfPerformanceCountry, defCodes, url, updateType (monitor mode: new | changed; otherwise null), previous (changed rows: awardAmount, totalOutlays, endDate, lastModified), changeHash, source. compact rows: awardKey, awardId, updateType, changeHash, category, recipientName, awardAmount, totalOutlays, lastModified, endDate, awardingAgency, description, previous, url.

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

Fields: ok, count, chargeEvent, chargedCount, chargeLimitReached (only when hit), outputFormat, awardCategories, queriedFrom, queriedTo, dateType, requestBodies, categoriesCompleted / categoriesPartial / categoriesSkipped (only when the request cap was hit: which award categories finished, were cut, or were not queried this run), autoWindow (only when used), truncated (true only when more matching rows exist beyond maxItems, the cost limit or the request cap), incomplete, olderMatchesSkipped (baseline monitor runs), truncationNote, message, warnings, onlyNewSinceLastRun, watermarkStore, watermarkKey, baselineRun, cursorBefore, cursorAfter, consecutiveCappedRuns (monitor runs in a row that hit the request cap), newCount, changedCount (both counted from pushed rows), skippedUnchanged, usaspendingRequests (total, retries, throttled, capped, minIntervalMs, perRunCap, userAgent), disclaimer. On failure: ok false, error.

# 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 = {
    "awardCategories": [
        "contracts",
        "grants"
    ],
    "keywords": [
        "cybersecurity"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("brightish_ascent/usaspending-awards-monitor").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 = {
    "awardCategories": [
        "contracts",
        "grants",
    ],
    "keywords": ["cybersecurity"],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("brightish_ascent/usaspending-awards-monitor").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 '{
  "awardCategories": [
    "contracts",
    "grants"
  ],
  "keywords": [
    "cybersecurity"
  ],
  "maxItems": 20
}' |
apify call brightish_ascent/usaspending-awards-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,brightish_ascent/usaspending-awards-monitor"
        }
    }
}
```

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/tEvDecEwhejxgM2Gw/builds/vf3coK8VGm9Q66o5G/openapi.json