# USAspending Federal Spending Search (`ryanclinton/usaspending-search`) Actor

Search and extract US federal government spending data directly from the official USAspending.gov API. This actor provides structured access to over $2 trillion in annual federal spending across contracts, grants, loans, direct payments, and other financial assistance programs.

- **URL**: https://apify.com/ryanclinton/usaspending-search.md
- **Developed by:** [Ryan Clinton](https://apify.com/ryanclinton) (community)
- **Categories:** AI, Developer tools
- **Stats:** 9 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 record fetcheds

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

## USAspending Federal Spending Search

![Federal market intelligence from USAspending.gov — not just award rows](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/hero.png)

Federal market intelligence from USAspending.gov. Search contracts, grants, loans, direct payments and IDVs across $2 trillion in annual federal spending — then go further: analyze market concentration, identify expiring contracts and recompete opportunities, profile contractors, monitor competitors, track contractor momentum, and discover which federal markets are growing fastest. Every run returns clean, normalized award records plus a run-level intelligence summary, with direct links back to USAspending.gov.

**Built for** capture managers, business development teams, federal contractors, government consultants, market-intelligence analysts, journalists, and researchers who need more than award rows.

#### What makes this premium

- **Market structure, not just rows.** Each run emits a summary record with a Herfindahl-Hirschman Index over recipient dollar share, a concentration band, top recipients with market-share %, recipient diversity (repeat vs one-off recipients within the result set), and per-state / per-agency breakdowns.
- **Search depth.** Filter by NAICS industry codes, PSC product/service codes, recipient and place-of-performance states, an amount band (min and max), multiple keywords, and the date field to filter on. Don't know the codes? Enter plain-language terms and the actor resolves them.
- **Multiple award categories in one run.** Search across award categories together; results are merged, re-ranked, and broken down by type.
- **Expiring-contract intelligence.** Every contract carries a recompete signal and days-until-end; the summary rolls up the dollar value expiring inside your window with a one-glance opportunity-density level — the BD pipeline a raw search can't give.
- **Scheduled monitoring.** Name a watchlist and the actor tracks what's new and what changed since the last run (`changeType` per award) plus which recipients are gaining or losing share — a Federal Spending Monitor, not just a search.
- **Capture pipeline, not award rows.** Every contract gets a `captureWorthiness` verdict (`high` / `medium` / `low`) with the exact `captureSignals` behind it (large value, ending soon, competitive market) — and a `captureScore` you can sort on to rank a BD pipeline instead of eyeballing a flat list.
- **Operating modes.** One actor, five jobs: `search` (award rows + analytics), `market` (a market-scan digest — should I care about this market?), `contractor` (a recipient profile with incumbent vulnerability), `monitor` (track what changed), and `discover` (rank the fastest-growing federal markets).
- **Anomaly flags + priority score.** Each award is flagged (above-95th-percentile amount, ending soon, single-recipient dominance, foreign recipient, and more) and scored 0-100 so the most unusual awards sort to the top.
- **Reproducible + agent-ready.** A query fingerprint makes each run citable; the summary and resolved query are mirrored to the key-value store for BI tools and agents. No API key, deterministic, no LLM.

![500 award rows in, 8 high-priority awards out — a capture pipeline](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/before-after.png)

| Capability | USAspending.gov website | Raw API | This actor |
|------------|:----------------------:|:-------:|:----------:|
| Keyword / agency / recipient search | Yes | Yes | Yes |
| Export structured data | Limited | Requires coding | Yes |
| NAICS / PSC / location filters | Partial | Yes | Yes |
| Search by plain-language industry terms | No | No | Yes |
| Multiple award categories per query | No | No | Yes |
| Market concentration (HHI) | No | No | Yes |
| Recompete / expiring-contract pipeline | No | No | Yes |
| Anomaly flags + priority score | No | No | Yes |
| Capture-worthiness pipeline | No | No | Yes |
| Market-health score | No | No | Yes |
| Incumbent vulnerability | Partial (paid) | No | Yes |
| Recipient share momentum | No | No | Yes |
| Scheduled change monitoring | No | No | Yes |

![Raw award rows or decision-ready capture pipeline — a capability comparison](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/comparison.png)

***

### What a federal market looks like in 30 seconds

1. Search `cybersecurity` at the Department of Defense.
2. Read the summary record: a $2.8B market, concentration `concentrated` (HHI 1,840), 7 contracts worth $412M expiring inside 180 days, Booz Allen Hamilton gaining share.
3. Add a `watchlistName` and schedule it weekly.
4. Each run tells you what changed: new awards appearing, contract values increasing, market share shifting, and whether the market is growing or consolidating over time.

That is the workflow this actor replaces: a capture manager's morning spent in USAspending exports and spreadsheets, returned as one structured run.

![What the actor adds — from USAspending awards through capture signals, analytics, momentum and history to decision digests](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/intelligence-layers.png)

### Common federal contracting jobs

Buyers search by the job they need done, not by feature. Map your job to a mode:

| I want to... | Use |
|--------------|-----|
| Find federal contracts expiring soon (recompete pipeline) | Search + `includeExpiringOnly`, or read `recompetePipeline` |
| Build a prioritized BD pipeline | Search + sort by `captureWorthiness` / `captureScore` |
| Evaluate whether a market is worth entering | `mode: "market"` |
| Analyze a contractor and spot a vulnerable incumbent | `mode: "contractor"` |
| Find which federal markets are growing fastest | `mode: "discover"` |
| Monitor competitors and get alerted when things change | `mode: "monitor"` + `watchlistName` |
| Track whether a market is consolidating over time | `mode: "monitor"` → `marketHistory` |

### Ready-to-run examples

One-click presets for the most common federal-contracting jobs — each opens with the input filled in:

- **[Find Federal Contracts Expiring Soon](https://apify.com/ryanclinton/usaspending-search/examples/usaspending-expiring-contracts)** — the recompete pipeline: contracts entering the re-bid window with days remaining and the incumbent.
- **[Federal Contract Capture Opportunities](https://apify.com/ryanclinton/usaspending-search/examples/usaspending-capture-opportunities)** — the contracts worth pursuing, each scored for capture-worthiness.
- **[Identify Incumbent Risk Opportunities](https://apify.com/ryanclinton/usaspending-search/examples/usaspending-incumbent-risk)** — vulnerable incumbents to displace, ranked by recompete exposure and at-risk value.
- **[Federal Contract Market Analysis](https://apify.com/ryanclinton/usaspending-search/examples/usaspending-market-analysis)** — concentration (HHI), top contractors, incumbent risk and the spending trend for a market.
- **[Analyze a Federal Contractor](https://apify.com/ryanclinton/usaspending-search/examples/usaspending-contractor-profile)** — a contractor's market share, share trend, active awards, expiring value and incumbent risk.
- **[Fastest-Growing Federal Markets](https://apify.com/ryanclinton/usaspending-search/examples/usaspending-growing-markets)** — federal markets ranked by fiscal-year spending growth.

See all examples on the [examples page](https://apify.com/ryanclinton/usaspending-search/examples).

### Questions this actor answers

- Who is winning Department of Defense cybersecurity contracts?
- Which federal contracts are expiring in the next 180 days?
- Which contractors are gaining or losing federal market share?
- Which federal markets are growing fastest right now?
- Which agencies are increasing their spending, and how competitively do they buy?
- How concentrated is a federal market — is one contractor dominant?
- Which competitors just won new awards or had a contract value increase?
- Which incumbents are most vulnerable to losing their work at recompete?

### Popular workflows

- Find expiring DoD contracts
- Monitor competitors winning federal awards
- Track federal AI spending
- Analyze a contractor's federal market share
- Identify federal cybersecurity opportunities
- Discover growing government markets
- Monitor recompete pipelines
- Build a federal BD capture pipeline

**How the metrics are derived.** All market-intelligence metrics come from the awards returned by your query and your watchlist history. They are deterministic analytical signals computed from public federal data, not predictions or forecasts.

***

### Operating modes

One actor, five jobs — set `mode` to reshape the output over the same federal data.

| Mode | Answers | Adds |
|------|---------|------|
| `search` (default) | "Find me the awards." | Award rows + analytics summary. |
| `market` | "Should I care about this market?" | A `market-scan` digest: market-health score, trend, concentration, recompete value, gaining/losing share, top incumbents with vulnerability. |
| `contractor` | "How strong is this contractor, and is the incumbent vulnerable?" | A `contractor-profile` digest for the recipient you search: market share, share trend, active awards, expiring value, vulnerability, top agencies. |
| `monitor` | "What changed in my market since last run?" | Cross-run change tracking (set a `watchlistName`): per-award `changeType`, recipient share momentum, `marketMovements`, and dated historical market snapshots. |
| `discover` | "Where should I be looking?" | Ignores the keyword and ranks a curated set of federal markets by spending growth (`topGrowingMarkets`, `topEmergingMarkets`, leaderboard). |

```json
{ "mode": "market", "keyword": "cybersecurity", "agency": "Department of Defense" }
```

```json
{ "mode": "discover" }
```

```json
{ "mode": "contractor", "recipient": "Booz Allen Hamilton", "maxResults": 200 }
```

```json
{ "mode": "monitor", "keyword": "zero trust", "watchlistName": "ztc-pipeline", "emitOnly": "new_or_changed" }
```

***

![Capture pipeline, recompete radar, market concentration and scheduled monitoring](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/feature-callouts.png)

### Why use USAspending Federal Spending Search?

The USAspending.gov website is the authoritative source for federal spending data, maintained by the US Department of the Treasury. But manually searching the site is slow, repetitive, and limited -- there is no built-in way to export structured data at scale, schedule recurring searches, or integrate results into automated workflows.

The underlying API is powerful but requires building POST request bodies with complex filter objects, handling page-based pagination, managing different field sets for different award types (loans use entirely different fields than contracts), and transforming nested response structures into usable formats. That is a significant engineering investment before you get a single row of data.

This actor handles all of that complexity. It builds the correct API request for your chosen award type, paginates through results automatically, normalizes loan and non-loan fields into a consistent output schema, constructs recipient location strings, and generates direct USAspending.gov URLs for every award. You get clean, flat JSON records ready for analysis, export, or integration -- without writing a single line of code.

Running on Apify's cloud infrastructure, you can schedule daily or weekly monitoring runs, push results to Google Sheets or Slack, trigger webhooks for downstream processing, and access data programmatically through the Apify API in JSON, CSV, or Excel format.

***

### Key features

- **Six award type categories** -- search contracts, grants, loans, direct payments, IDVs (Indefinite Delivery Vehicles), and other financial assistance independently, each with the correct API codes and field mappings.
- **Keyword search** -- filter awards by description keywords such as "cybersecurity," "renewable energy," "artificial intelligence," or any topic area.
- **Agency filtering** -- narrow results to a specific top-tier awarding agency like the Department of Defense, NASA, or the Department of Energy.
- **Recipient search** -- find all awards going to a specific contractor or organization by name (e.g., "Lockheed Martin," "Deloitte," "RAND Corporation").
- **Date range filtering** -- restrict results to a specific fiscal period using YYYY-MM-DD format, with data available back to fiscal year 2008 (2007-10-01).
- **Minimum amount threshold** -- filter out small awards by setting a dollar floor (e.g., only contracts above $1,000,000).
- **Automatic pagination** -- the actor handles multi-page API responses transparently, fetching up to 1,000 results across multiple requests with built-in rate limiting.
- **Consistent output schema** -- loans use different fields (Loan Value, Issued Date) than contracts and grants (Award Amount, Start/End Date), but the actor normalizes everything into a single consistent format.
- **Direct USAspending links** -- every output record includes a URL linking directly to the full award page on USAspending.gov for verification and further research.
- **No API key required** -- the USAspending API is free, open, and requires no registration or authentication tokens.
- **Market-concentration analytics** -- every run emits a summary record answering the question raw rows cannot: how concentrated is this spending (Herfindahl-Hirschman Index + a concentrated/competitive/fragmented band), who the top recipients are by dollar share, which agencies dominate, and where the money lands by state.
- **Award-size tiering and active flags** -- each award is classified `mega` / `large` / `mid` / `small` by dollar value, tagged with its period-of-performance length in days, and flagged active when its end date is in the future -- so you can sort, filter, and route without re-deriving anything.
- **Fiscal-year spending trend** -- opt in to see whether spend for your filters is rising, falling, or stable across fiscal years, computed from the official aggregate endpoint.

***

### How to use USAspending Federal Spending Search

1. Navigate to the [USAspending Federal Spending Search](https://apify.com/ryanclinton/usaspending-search) actor on the Apify Store.
2. Click **Try for free** to open the actor in Apify Console.
3. Enter an optional **keyword** to search across award descriptions (e.g., "cybersecurity," "renewable energy").
4. Select an **award type** -- contracts (default), grants, loans, direct payments, IDVs, or other financial assistance.
5. Optionally add filters for **agency**, **recipient name**, **date range**, or **minimum dollar amount**.
6. Set **max results** (default 25, maximum 1,000) and click **Start**.
7. Download results as JSON, CSV, or Excel from the Dataset tab, or connect via API.

#### Using the API

You can start the actor programmatically via the Apify API. See the [API & integration](#api--integration) section below for Python, JavaScript, and cURL examples.

***

### Input parameters

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `mode` | String | No | `search` | `search` / `market` / `contractor` / `monitor` / `discover`. See "Operating modes" above. |
| `keyword` | String | No | -- | Search term matched against award descriptions (e.g., "artificial intelligence", "infrastructure", "wildfire suppression"). |
| `keywords` | String\[] | No | -- | Additional keywords, matched as ANY (OR) by the API, combined with `keyword`. |
| `awardType` | String | No | `contracts` | Category of federal award. Options: `contracts`, `grants`, `loans`, `direct_payments`, `other`, `idvs`. |
| `awardTypes` | String\[] | No | -- | Search several award types in one run (e.g. `["contracts","grants"]`). Each is fetched as its own API group, then merged and ranked. Takes precedence over `awardType`. |
| `agency` | String | No | -- | Top-tier awarding agency name (e.g., "Department of Defense"). Must be the exact official name unless `resolveAgency` is on. |
| `resolveAgency` | Boolean | No | `false` | Resolve a loose agency name ("DoD", "NASA") to its canonical top-tier name via the autocomplete endpoint before filtering. Costs one extra API call. |
| `recipient` | String | No | -- | Recipient or contractor name to search for (e.g., "Lockheed Martin", "Booz Allen Hamilton"). |
| `naicsCodes` | String\[] | No | -- | Filter by NAICS industry codes (e.g. `["541512"]` Computer Systems Design Services). |
| `naicsSearch` | String\[] | No | -- | Plain-language industry terms (e.g. `["cybersecurity","cloud"]`) resolved to NAICS codes via autocomplete. Merged with `naicsCodes`. |
| `pscCodes` | String\[] | No | -- | Filter by Product/Service Codes (e.g. `["D399"]`). |
| `pscSearch` | String\[] | No | -- | Plain-language product/service terms resolved to PSC codes via autocomplete. Merged with `pscCodes`. |
| `recipientStates` | String\[] | No | -- | Filter by recipient location, 2-letter US state codes (e.g. `["VA","MD"]`). |
| `placeOfPerformanceStates` | String\[] | No | -- | Filter by place of performance, 2-letter US state codes. |
| `dateRange` | String | No | -- | Date range in the format `YYYY-MM-DD to YYYY-MM-DD` (e.g., "2024-01-01 to 2024-12-31"). Earliest supported date is 2007-10-01. |
| `dateType` | String | No | `action_date` | Which date `dateRange` filters on: `action_date`, `date_signed`, `last_modified_date`, or `new_awards_only`. |
| `minAmount` | Number | No | -- | Minimum award amount in US dollars (e.g., 1000000 for $1M+). |
| `maxAmount` | Number | No | -- | Maximum award amount in US dollars. Combine with `minAmount` for an amount band. |
| `sortBy` | String | No | `amount` | Order results by award `amount` or `recipient` name. |
| `sortOrder` | String | No | `desc` | `desc` (default) or `asc`. |
| `recompeteWindowDays` | Integer | No | 180 | Contracts ending within this many days are flagged as recompete opportunities. |
| `includeExpiringOnly` | Boolean | No | `false` | Emit only awards inside the recompete window. Suppressed awards are still counted in the summary. |
| `onlyFlagged` | Boolean | No | `false` | Emit only awards carrying at least one anomaly flag. Suppressed awards are still counted in the summary. |
| `maxResults` | Integer | No | 25 | Maximum number of awards to return. Minimum 1, maximum 1,000. |
| `outputProfile` | String | No | `standard` | Detail level per award record: `minimal` (decision headline), `standard` (full record minus long description), or `full` (every field). The run-level analytics summary is always included. |
| `includeTrend` | Boolean | No | `false` | Also compute the fiscal-year spending trend (rising / falling / stable) for these filters, added to the summary record. Costs one extra API call. |
| `watchlistName` | String | No | -- | Name a watchlist to turn on cross-run monitoring. The actor remembers each run's awards + recipient shares and tags the next run's awards with a `changeType`. First run is a baseline. |
| `emitOnly` | String | No | `all` | When monitoring: emit only `new`, `changed`, or `new_or_changed` awards (default `all`). Suppressed awards are still tracked and counted. |

#### Input example

**Find large DoD cybersecurity contracts:**

```json
{
    "keyword": "cybersecurity",
    "awardType": "contracts",
    "agency": "Department of Defense",
    "minAmount": 1000000,
    "maxResults": 50
}
```

**Search NIH grants for a specific organization:**

```json
{
    "keyword": "cancer research",
    "awardType": "grants",
    "agency": "Department of Health and Human Services",
    "recipient": "Johns Hopkins",
    "maxResults": 100
}
```

**Federal loans issued in 2024:**

```json
{
    "awardType": "loans",
    "dateRange": "2024-01-01 to 2024-12-31",
    "minAmount": 5000000,
    "maxResults": 200
}
```

#### Input tips

- **Use specific keywords** -- broad terms like "technology" or "services" return millions of results. More specific phrases like "quantum computing" or "wildfire suppression" produce focused results.
- **Agency names must be exact** -- use the full official name such as "Department of Defense" rather than abbreviations like "DoD." Check USAspending.gov for correct names.
- **Award types cannot be mixed** -- the USAspending API requires searching one award type per request. Run the actor separately for contracts and grants if you need both.
- **Date ranges start at FY2008** -- the earliest available data begins on 2007-10-01 (fiscal year 2008).
- **Combine filters for precision** -- using keyword + agency + date range together produces the most targeted results.

***

### Output

The dataset contains two record types, distinguished by the `recordType` field: one `award` record per result, plus a single `summary` analytics record per run.

#### Award records (`recordType: "award"`)

```json
{
    "recordType": "award",
    "schemaVersion": "2.0.0",
    "awardId": "W911NF23C0045",
    "title": "CYBERSECURITY OPERATIONS AND DEFENSE SUPPORT SERVICES",
    "awardType": "Contract",
    "awardAmount": 48750000,
    "awardSizeTier": "large",
    "awardingAgency": "Department of Defense",
    "fundingAgency": "Department of the Army",
    "recipientName": "BOOZ ALLEN HAMILTON INC.",
    "recipientLocation": "McLean, VA",
    "startDate": "2023-03-15",
    "endDate": "2028-03-14",
    "durationDays": 1826,
    "daysUntilEnd": 142,
    "isActive": true,
    "recompeteSignal": "recompete-window",
    "recompetePriority": "medium",
    "flags": ["amount_above_p95"],
    "priorityScore": 25,
    "description": "CYBERSECURITY OPERATIONS AND DEFENSE SUPPORT SERVICES FOR ARMY NETWORK ENTERPRISE TECHNOLOGY COMMAND",
    "usaspendingUrl": "https://www.usaspending.gov/award/CONT_AWD_W911NF23C0045_9700_-NONE-_-NONE-",
    "summary": "Contract: BOOZ ALLEN HAMILTON INC. (McLean, VA) — $48,750,000 from Department of Defense.",
    "extractedAt": "2026-02-17T14:30:00.000Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `recordType` | String | `award` for award rows. |
| `schemaVersion` | String | Output-contract version (additive within a major version). |
| `awardId` | String | Official award identification number assigned by the contracting agency. |
| `title` | String | Short description of the award (truncated to 500 characters). |
| `awardType` | String | Human-readable award type label: Contract, Grant, Loan, Direct Payment, IDV, or Other Financial Assistance. |
| `awardAmount` | Number or null | Total award value in US dollars. For loans, this is the loan face value. Null if no amount is recorded. |
| `awardSizeTier` | String or null | Size band: `mega` (≥$100M), `large` (≥$10M), `mid` (≥$1M), `small` (<$1M). Null when no amount is recorded. |
| `awardingAgency` | String | Name of the federal agency that made the award. |
| `fundingAgency` | String or null | Name of the agency providing the funding, if different from the awarding agency. |
| `recipientName` | String | Name of the company, organization, or individual receiving the award. |
| `recipientLocation` | String or null | City and state of the recipient (e.g., "McLean, VA"). Includes country name for non-US recipients. |
| `startDate` | String or null | Award start date (or issue date for loans) in YYYY-MM-DD format. |
| `endDate` | String or null | Award end date in YYYY-MM-DD format. Not available for loans. |
| `durationDays` | Number or null | Period-of-performance length in days. Null for loans and any award missing a date. |
| `daysUntilEnd` | Number or null | Days until the end date (negative if ended). Null for loans / no end date. |
| `isActive` | Boolean or null | True when the end date is in the future. Null when there is no end date (loans). |
| `recompeteSignal` | String or null | `expiring-soon` (≤90d) / `recompete-window` (≤window) / `active` / `ended`. Null for loans. A signal derived from the end date, not a prediction the agency will re-compete. |
| `recompetePriority` | String or null | `high` / `medium` / `low` for the recompete signal. Null for loans / no end date. |
| `flags` | String\[] | Deterministic anomaly flags (e.g. `amount_above_p95`, `ending_soon`, `single_recipient_dominance`, `foreign_recipient`). Empty when none fire. |
| `priorityScore` | Number | 0-100 attention score from the weighted flags (see weights below). Sort descending to surface the most unusual awards. |
| `captureScore` | Number | 0-100 BD pursue-worthiness (size + ending-soon + market competitiveness). A *different question* from `priorityScore`: "should I pursue this?" vs "is this unusual?". |
| `captureWorthiness` | String or null | `high` / `medium` / `low` from the capture score. Null for awards with no recompete dimension (loans / no end date). |
| `captureSignals` | String\[] | The deterministic reasons behind the capture verdict: `large_value`, `ending_soon`, `recompete_window`, `competitive_market`. Read these instead of asking "why this score?". |
| `changeType` | String or null | Monitoring only: `new_award` / `amount_increased` / `amount_decreased` / `contract_extended` / `unchanged` vs the prior watchlist run. Null without a watchlist. |
| `previousAmount` / `amountChange` | Number or null | Monitoring only: the award's amount on the prior run and the delta. Null on first sight. |
| `firstSeenAt` | String or null | Monitoring only: when the award was first observed under the watchlist. |
| `description` | String | Full description text of the award (present in `standard` and `full` profiles). |

**Priority score weights.** Deterministic, summed from the flags that fire (capped at 100): `amount_above_p95` +25, `ending_soon` +25, `single_recipient_dominance` +20, `recompete_window` +15, `short_duration_high_value` +15, `foreign_recipient` +10, `missing_amount` +5.
| `usaspendingUrl` | String | Direct link to the award page on USAspending.gov for full details and documentation. |
| `summary` | String | One plain-English line describing the award, quotable by an LLM or agent without joining fields. |
| `extractedAt` | String | ISO 8601 timestamp of when the data was extracted by this actor. |

(Fields shown are the `full` profile. `standard` omits `description`; `minimal` keeps only the decision headline: recordType, awardId, awardType, awardSizeTier, recipientName, awardAmount, awardingAgency, isActive, usaspendingUrl, summary.)

![Sample output — recipient, award amount, days until end, recompete signal, capture worthiness](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/output-table.png)

#### Summary analytics record (`recordType: "summary"`)

One per run, also mirrored to the key-value store under the `SUMMARY` key. It turns the result set into market intelligence:

```json
{
    "recordType": "summary",
    "schemaVersion": "2.0.0",
    "awardTypeLabel": "Contract",
    "awardsAnalyzed": 50,
    "totalAwardAmount": 2840000000,
    "averageAwardAmount": 56800000,
    "medianAwardAmount": 22500000,
    "p90AwardAmount": 180000000,
    "largestAward": { "recipientName": "LOCKHEED MARTIN CORPORATION", "amount": 410000000, "awardId": "..." },
    "awardSizeDistribution": { "mega": 8, "large": 31, "mid": 9, "small": 2, "unspecified": 0 },
    "byAwardType": [ { "awardType": "Contract", "awardCount": 50, "totalAmount": 2840000000 } ],
    "recipientConcentration": { "hhi": 1840, "level": "concentrated", "topRecipientSharePct": 24.1, "top5RecipientSharePct": 61.4, "distinctRecipients": 37 },
    "recipientDiversity": { "distinctRecipients": 37, "repeatRecipients": 6, "newRecipients": 31, "repeatRecipientSharePct": 38 },
    "topRecipients": [ { "recipientName": "LOCKHEED MARTIN CORPORATION", "awardCount": 4, "totalAmount": 684000000, "marketSharePct": 24.1 } ],
    "recipientMomentum": [ { "recipientName": "BOOZ ALLEN HAMILTON INC.", "shareCurrent": 18.4, "sharePrior": 12.1, "changePct": 52.1, "trend": "gaining_share" } ],
    "topAwardingAgencies": [ { "agency": "Department of Defense", "awardCount": 42, "totalAmount": 2510000000, "avgAwardSize": 59761904, "vendorDiversity": 31, "competitionLevel": "medium" } ],
    "topRecipientStates": [ { "state": "VA", "awardCount": 14, "totalAmount": 980000000, "expiringValue": 240000000 } ],
    "recompetePipeline": { "windowDays": 180, "expiringCount": 7, "expiringTotalValue": 412000000, "highPriorityCount": 3, "avgDaysRemaining": 124, "level": "high" },
    "marketMovements": [ { "movementType": "incumbent_loss", "detail": "ACME CORP lost share 22.0% → 14.0%", "entity": "ACME CORP", "magnitude": -36.4 } ],
    "monitoring": { "enabled": true, "watchlistName": "dod-cyber", "isBaselineRun": false, "runIndex": 4, "newAwards": 3, "changedAwards": 2 },
    "queryFingerprint": "a1b2c3d4e5f6a7b8",
    "resolutionWarnings": [],
    "query": { "keyword": "cybersecurity", "keywords": null, "awardTypes": ["contracts"], "agency": "Department of Defense", "recipient": null, "dateRange": null, "minAmount": 1000000, "maxAmount": null, "naicsCodes": null, "pscCodes": null },
    "spendingTrend": { "group": "fiscal_year", "periods": [], "direction": "rising", "recentAmount": 0, "priorAmount": 0, "changePct": 18.4 }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `awardsAnalyzed` | Number | Count of award records the analytics were computed over (all matched rows, before any output filter). |
| `totalAwardAmount` / `averageAwardAmount` / `medianAwardAmount` / `p90AwardAmount` | Number | Aggregate, mean, median, and 90th-percentile award value. |
| `largestAward` | Object or null | The single biggest award (recipient, amount, award ID). |
| `awardSizeDistribution` | Object | Count of awards in each size tier (mega / large / mid / small / unspecified). |
| `byAwardType` | Array | Per-award-type breakdown (count + dollars). One entry for single-type runs; multiple for multi-type. |
| `recipientConcentration` | Object | `hhi` (Herfindahl-Hirschman Index 0–10000 over recipient dollar share), `level` (`highly-concentrated` / `concentrated` / `competitive` / `fragmented`), `topRecipientSharePct`, `top5RecipientSharePct`, `distinctRecipients`. |
| `recipientDiversity` | Object | Repeat vs one-off recipients within the result set: `repeatRecipients`, `newRecipients`, `repeatRecipientSharePct`. A within-query diversity signal, not lifetime federal-incumbent history. |
| `topRecipients` | Array | Top 10 recipients by dollars, each with award count, total, and market-share %. |
| `recipientMomentum` | Array | Monitoring only: top recipients with `shareCurrent`, `sharePrior`, `changePct`, and `trend` (`gaining_share` / `losing_share` / `stable` / `new`). Empty without a watchlist. |
| `topAwardingAgencies` | Array | Top 10 awarding agencies by dollars, each with `avgAwardSize`, `vendorDiversity` (distinct recipients), and a `competitionLevel` (`high` / `medium` / `low`) buying-behaviour read. |
| `topRecipientStates` | Array | Top 10 recipient states by re-bid value, each with `expiringValue` (the dollar value expiring in that state) and `totalAmount`. |
| `recompetePipeline` | Object | Contracts expiring inside `recompeteWindowDays`: `expiringCount`, `expiringTotalValue`, `highPriorityCount`, `avgDaysRemaining`, and a one-glance opportunity-density `level` (`high` / `medium` / `low`). |
| `marketMovements` | Array | Monitoring only: typed "what changed" events — `share_shift`, `incumbent_loss`, `new_funding` — each with a plain-English `detail`. Empty on a baseline run. |
| `marketHistory` | Object or null | Monitoring only: the dated snapshot series and its diffs — `spendChangePctVsPrior`, `spendChangePctVsEarliest`, `spendTrend`, `concentrationTrend` (`consolidating` / `fragmenting` / `stable`), plus the recent `snapshots[]`. The longitudinal "is this market growing or consolidating over time" read. `insufficient-data` until two runs exist. |
| `monitoring` | Object | `enabled`, `watchlistName`, `isBaselineRun`, `runIndex`, `newAwards`, `changedAwards`. Reflects the cross-run watchlist state. |
| `queryFingerprint` | String | Stable 16-char hash of the resolved query — cite it to reproduce the exact search. |
| `resolutionWarnings` | Array | Any agency-name resolutions applied (when `resolveAgency` is on). |
| `query` | Object | Echo of the search filters that produced this run. |
| `spendingTrend` | Object or null | Present only when `includeTrend` is set: fiscal-year trend `direction` plus recent/prior amounts and `changePct`. |

#### Market-scan digest (`recordType: "market-scan"`, market mode)

In `mode: "market"`, one extra record answers "should I care about this market?":

```json
{
    "recordType": "market-scan",
    "market": "cybersecurity",
    "marketHealthScore": 78,
    "classification": "good",
    "marketTrend": "expanding",
    "concentrationLevel": "competitive",
    "recompeteValue": 412000000,
    "newMoney": 90000000,
    "gainingShare": [ { "recipientName": "BOOZ ALLEN HAMILTON INC.", "shareCurrent": 18.4, "trend": "gaining_share" } ],
    "losingShare": [],
    "topIncumbents": [ { "recipientName": "ACME CORP", "marketSharePct": 14.0, "shareTrend": "losing_share", "expiringValue": 120000000, "vulnerabilityScore": 71, "incumbentRisk": "high" } ],
    "scoreComponents": [ { "name": "spendingTrend", "available": true, "contribution": 25 }, { "name": "newEntrants", "available": false, "contribution": 12 } ]
}
```

**Market Health Score = Competitiveness (25%) + Recompete Density (25%) + Spending Growth (25%) + New Entrants (25%).** Competitiveness rewards a more fragmented market; recompete density rewards more re-bid value; spending growth rewards rising fiscal-year spend; new entrants rewards fresh money since last run. Components that need an opt-in (`includeTrend` for the trend, a `watchlistName` for new entrants) are marked `available: false` in `scoreComponents` and contribute a neutral baseline — the score is honest about what it could and couldn't measure rather than scoring a missing input as zero.

#### Contractor-profile digest (`recordType: "contractor-profile"`, contractor mode)

![Contractor profile — federal market share, share trend, active awards, expiring value, incumbent risk](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/executive-report.png)

In `mode: "contractor"` with a `recipient` set, one extra record profiles that contractor over the returned awards:

```json
{
    "recordType": "contractor-profile",
    "recipientName": "Booz Allen Hamilton",
    "marketSharePct": 12.4,
    "shareTrend": "gaining_share",
    "activeAwards": 38,
    "totalAwardValue": 684000000,
    "expiringValue": 120000000,
    "vulnerabilityScore": 24,
    "incumbentRisk": "low",
    "topAgencies": [ { "agency": "Department of Defense", "awardCount": 21, "totalAmount": 410000000 } ]
}
```

This profiles the awards the recipient query returned, not the contractor's full federal history. Set a `watchlistName` for share-trend accuracy across runs.

#### Market-discovery digest (`recordType: "market-discovery"`, discover mode)

![Discovery products — fastest-growing federal markets and the recompete pipeline](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/discovery-cards.png)

In `mode: "discover"`, the actor ignores the keyword and ranks a curated set of high-value federal contracting markets by fiscal-year spending growth. The scanned set is: artificial intelligence, cybersecurity, cloud computing, health information technology, logistics, engineering services, professional services, research and development, telecommunications, and facilities maintenance. Each is measured with one spending-over-time query, then ranked into fastest-growing and emerging (small-but-rising) lists:

```json
{
    "recordType": "market-discovery",
    "marketsScanned": 10,
    "topGrowingMarkets": [ { "market": "artificial intelligence", "recentSpend": 1840000000, "growthPct": 41.2, "trend": "rising" } ],
    "topEmergingMarkets": [ { "market": "facilities maintenance", "recentSpend": 210000000, "growthPct": 28.0, "trend": "rising" } ],
    "leaderboard": [ "...all scanned markets ranked by growth..." ]
}
```

This ranks a curated candidate set, not every federal market. Run `mode: "market"` on a specific market for its full recompete + incumbent detail.

***

### Monitoring federal spending changes

![What changed since last run — new awards, contract value increases, share shifts, concentration](https://apifyforge.com/readme-assets/ryanclinton-usaspending-search/change-feed.png)

Set a `watchlistName` and schedule the actor to turn a one-off search into a continuous monitor. The actor remembers the awards and recipient shares it saw under that name and reports what changed on each subsequent run.

- **First run** is a baseline: every award is `new_award`, `recipientMomentum` trends are `new`, and `monitoring.isBaselineRun` is `true`. Change detection activates from the second run.
- **From the second run on**, each award carries a `changeType` (`new_award` / `amount_increased` / `amount_decreased` / `contract_extended` / `unchanged`) with `previousAmount` and `amountChange`, and the summary's `recipientMomentum` shows which contractors are gaining or losing share.
- **`emitOnly`** narrows the dataset to `new`, `changed`, or `new_or_changed` awards for low-noise alerting — suppressed awards are still tracked and counted in the summary.
- **Historical snapshots accumulate over time.** Each run banks a dated market aggregate (total spend, concentration, distinct recipients) under the watchlist. The `marketHistory` block then answers "is this market growing or consolidating over time" with real evidence — `spendChangePctVsEarliest` and a `concentrationTrend` of `consolidating` / `fragmenting`. This is the moat: a competitor can clone the analytics, but not the months of history your watchlist has banked.
- State is stored per watchlist name, so two schedules with different names never interfere. The history is bounded; the longer you run a watchlist, the richer its momentum, change record, and snapshot series.

Pair a scheduled run with the `changes` dataset view and an Apify webhook / Slack integration to get a "what's new in my federal market" digest with no post-processing.

### Use cases

- **Government contracting research** -- identify which companies win the largest federal contracts in your industry and track spending trends by agency, keyword, or time period.
- **Grant opportunity analysis** -- discover which organizations receive federal grants in specific research areas to benchmark your own grant applications and identify potential collaborators.
- **Competitive intelligence** -- monitor what contracts your competitors are winning from federal agencies and at what dollar amounts, broken down by award type and time period.
- **Journalism and transparency** -- investigate how taxpayer money is allocated across agencies, programs, and geographic regions with structured, exportable data.
- **Policy analysis** -- track federal spending patterns by agency, award type, or time period to support policy research, legislative advocacy, and budget analysis.
- **Business development** -- identify federal agencies that are actively spending in your product or service area to target BD efforts and build a qualified pipeline.
- **Due diligence** -- verify a company's claimed government contracts and check the actual dollar values of their federal awards before making investment or partnership decisions.
- **Academic research** -- build datasets of federal spending for economics, political science, or public administration research projects with clean, structured data.
- **Loan portfolio analysis** -- search federal loan programs to understand which organizations receive government-backed financing and at what face values.
- **Spending alerts** -- schedule recurring runs to monitor new awards in a specific area and trigger notifications when large contracts or grants are issued.

***

### API & integration

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_API_TOKEN")

run = client.actor("ryanclinton/usaspending-search").call(run_input={
    "keyword": "cybersecurity",
    "awardType": "contracts",
    "agency": "Department of Defense",
    "minAmount": 1000000,
    "maxResults": 100,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"${item['awardAmount']:,.0f} -- {item['recipientName']} -- {item['title'][:80]}")
```

#### JavaScript

```javascript
import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_APIFY_API_TOKEN" });

const run = await client.actor("ryanclinton/usaspending-search").call({
    keyword: "cybersecurity",
    awardType: "contracts",
    agency: "Department of Defense",
    minAmount: 1000000,
    maxResults: 100,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
    console.log(`$${item.awardAmount?.toLocaleString()} -- ${item.recipientName} -- ${item.title.slice(0, 80)}`);
}
```

#### cURL

```bash
## Start the actor
curl -X POST "https://api.apify.com/v2/acts/ryanclinton~usaspending-search/runs?token=YOUR_APIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "cybersecurity",
    "awardType": "contracts",
    "agency": "Department of Defense",
    "minAmount": 1000000,
    "maxResults": 100
  }'

## Retrieve results (use the defaultDatasetId from the run response)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_APIFY_API_TOKEN&format=json"
```

#### Integrations

The output dataset can be consumed through any of Apify's built-in integrations:

- **Google Sheets** -- automatically export federal spending data to a spreadsheet for team review and analysis.
- **Slack / Email** -- receive notifications when new large awards are detected in scheduled runs.
- **Webhooks** -- push results to your CRM, BI platform, or custom data pipeline.
- **Zapier / Make** -- connect to thousands of apps for automated workflow triggers.
- **Amazon S3** -- archive results to cloud storage for long-term trend analysis.
- **API access** -- retrieve results programmatically in JSON, CSV, XML, or Excel format via the Apify dataset API.

***

### Use in Dify

Drop this actor into [Dify](https://docs.apify.com/platform/integrations/dify) workflows via the Apify plugin's Run Actor node. It returns classified, concentration-scored federal spending as structured JSON: a `recordType` discriminator (`award` / `summary` / `error`), an `awardSizeTier` per award (`mega` / `large` / `mid` / `small`), a market `recipientConcentration.level` (`highly-concentrated` / `concentrated` / `competitive` / `fragmented`), and an opt-in `spendingTrend.direction` (`rising` / `falling` / `stable`) — the enums your downstream node branches on. A raw API wrapper pointed at USAspending returns paginated award rows; this returns a market-structure read your workflow can route on.

- **Actor ID:** `ryanclinton/usaspending-search`
- **Sample input** (competitive intelligence on a federal market):

```json
{
    "keyword": "cybersecurity",
    "awardType": "contracts",
    "agency": "Department of Defense",
    "minAmount": 1000000,
    "maxResults": 200,
    "includeTrend": true
}
```

- **Branching example.** Filter the dataset to the `summary` record (`recordType == "summary"`), then route a Dify if/else node on the analytics it carries:
  - `recipientConcentration.level == "highly-concentrated"` → escalate to a "concentrated market — review incumbent dominance" branch.
  - `spendingTrend.direction == "rising"` → route to an "expanding market" branch; `"falling"` → a "contracting market" branch.
  - On the per-award rows, branch on `awardSizeTier == "mega"` to fan out only the largest awards, on `isActive == true` to act only on live periods of performance, or on `recompeteSignal == "expiring-soon"` to route imminent re-bid opportunities to a BD queue.
  - Sort or threshold on `priorityScore` (0-100) to surface only the most unusual awards, and read each row's `flags[]` to label why.
  - Branch on `captureWorthiness == "high"` to route only the awards a BD team should pursue, or filter the dataset to `recordType == "market-scan"` and branch on `classification` / `marketTrend` to decide whether a market is worth entering.
  - In monitoring mode, branch on `changeType == "new_award"` to alert only on new awards, or `changeType == "amount_increased"` to route contract growth — the stable enum a scheduled Dify/Make/n8n flow fires on without parsing prose.
- The `topRecipients[]`, `topAwardingAgencies[]` and `recipientMomentum[]` arrays are usable verbatim — no LLM rewriting — to populate a Slack digest or a downstream enrichment step.
- Opt-in modes Dify workflows leverage: `watchlistName` (scheduled change monitoring), `emitOnly` (new/changed only), `includeTrend` (fiscal-year trend), `includeExpiringOnly` (recompete pipeline only).

***

### How it works

1. **Input parsing** -- the actor reads your search parameters and validates the award type against six supported categories (contracts, grants, loans, direct\_payments, other, idvs).

2. **Filter construction** -- a POST request body is built with the correct award type codes (e.g., contracts = A/B/C/D, grants = 02/03/04/05), along with keyword, agency, recipient, date range, and minimum amount filters.

3. **Field selection** -- the actor selects the appropriate field set based on award type. Loans use different fields (Loan Value, Subsidy Cost, Issued Date) than standard awards (Award Amount, Start Date, End Date).

4. **Paginated fetching** -- the actor sends POST requests to the USAspending API (`api.usaspending.gov/api/v2/search/spending_by_award/`), fetching up to 100 results per page. It continues paginating until the requested number of results is reached or no more results are available, with a 300ms delay between requests.

5. **Transformation** -- each raw API result is normalized into a consistent output schema. Loan fields are mapped to the same output fields as standard awards, recipient location is assembled from city/state/country components, and a direct USAspending.gov URL is constructed from the internal award ID.

6. **Output** -- clean JSON records are pushed to the Apify dataset one at a time. A summary log shows the total count, aggregate dollar amount, top awarding agencies, and top recipients.

```
Input (keyword, awardType, agency, recipient, dateRange, minAmount)
  |
  v
+---------------------------------------------+
| Filter Builder                              |
| - Award type codes (A/B/C/D for contracts)  |
| - Keywords, agency, recipient filters       |
| - Date range, minimum amount                |
+---------------------+-----------------------+
                      |
                      v
+---------------------------------------------+
| USAspending API (POST)                      |
| api.usaspending.gov/api/v2/search/          |
|   spending_by_award/                        |
| - 100 per page, sorted by amount desc      |
| - 300ms delay between pages                 |
| - Up to 10 pages (1,000 results max)        |
+---------------------+-----------------------+
                      |
                      v
+---------------------------------------------+
| Transform & Normalize                       |
| - Map loan fields to standard schema        |
| - Build recipient location string           |
| - Construct USAspending.gov award URL       |
| - Truncate title to 500 chars               |
+---------------------+-----------------------+
                      |
                      v
+---------------------------------------------+
| Output to Apify Dataset                     |
| - JSON records with 13 fields each          |
| - Summary: total amount, top agencies,      |
|   top recipients                            |
+---------------------------------------------+
```

***

### Performance & cost

USAspending Federal Spending Search is extremely cost-efficient. It runs with only 256 MB of memory and calls a free government API -- no web scraping or browser rendering involved.

| Scenario | Results | Pages | Estimated time | Estimated cost |
|----------|---------|-------|----------------|----------------|
| Quick lookup | 25 | 1 | ~5 sec | ~$0.001 |
| Standard search | 100 | 1 | ~8 sec | ~$0.002 |
| Deep scan | 500 | 5 | ~20 sec | ~$0.005 |
| Maximum extraction | 1,000 | 10 | ~40 sec | ~$0.01 |
| Daily monitoring (1 month) | 100/day | 1/day | ~8 sec/run | ~$0.06/month |

**Apify Free Tier:** New Apify accounts receive $5 of free platform credits each month. This is enough to run the actor hundreds of times per month at no cost.

**USAspending API:** The API is completely free with no API key, no registration, and no rate limits for reasonable usage.

***

### Limitations

- **Award-type groups are fetched separately** -- the USAspending API requires one award-type group per request. To search several types in one run, pass `awardTypes` (e.g. `["contracts","grants","loans"]`); the actor fetches each group, then merges and re-ranks the results and breaks them down by type.
- **1,000 result maximum** -- the actor caps at 1,000 results per run (100 per page, 10 pages). For larger datasets, narrow your search with date ranges, keywords, or agency filters and run multiple times.
- **Agency names must be exact** -- the agency filter requires the full official top-tier agency name (e.g., "Department of Defense," not "DoD" or "Pentagon"). Misspelled or abbreviated names will return no results.
- **Federal spending only** -- USAspending.gov tracks only federal government spending. State, local, and tribal government data is not available through this API.
- **Data update lag** -- USAspending.gov data is updated monthly by the Treasury Department. Recent awards may take 30-90 days to appear after they are obligated.
- **Loan end dates unavailable** -- the USAspending API does not return end dates for loan awards. The `endDate` field will always be null for loan searches.
- **No sub-award data** -- this actor searches prime awards only. Sub-award and sub-contract data is available through a different USAspending API endpoint not covered by this actor.

***

### Responsible use

- **Public data only** -- all data returned by this actor comes from publicly available federal spending records on USAspending.gov. No private or restricted information is accessed.
- **Respect API capacity** -- while the USAspending API has no formal rate limits, the actor includes a 300ms delay between page requests. Avoid scheduling excessively frequent runs that could burden the API.
- **Accuracy verification** -- while the actor normalizes and structures the data, always verify critical details on the official USAspending.gov website before making business, investment, or reporting decisions.
- **Intended purposes** -- this data is provided for research, journalism, business development, policy analysis, and transparency purposes. Use it responsibly and in compliance with applicable laws.
- **Recipient information** -- recipient names and locations are public record. Do not use this data for harassment, unsolicited marketing, or any purpose that violates recipient privacy expectations.

***

### FAQ

**Do I need a USAspending API key?**
No. The USAspending API is completely free and open to the public. No registration, API key, or authentication of any kind is required.

**How current is the data?**
USAspending.gov data is updated monthly by the Treasury Department. Recent awards may take 30-90 days to appear in the system after they are obligated by the awarding agency.

**Can I search for multiple award types at once?**
Yes. Pass `awardTypes` as an array (e.g. `["contracts","grants"]`). The actor fetches each type as its own API request, then merges, re-ranks, and breaks the results down by type in the summary record. The single `awardType` field still works for one type at a time.

**What is an IDV?**
An IDV (Indefinite Delivery Vehicle) is a contract that does not specify a firm quantity of supplies or a fixed scope of work at the time of award. This includes GWAC contracts (Government-Wide Acquisition Contracts), Federal Supply Schedules (GSA Schedules), and blanket purchase agreements.

**Why are some award amounts null?**
Some awards, particularly those in early stages or certain assistance programs, may not have a dollar amount recorded in the system yet. The `awardAmount` field will be null in these cases.

**Can I search for state or local government spending?**
No. USAspending.gov tracks only federal government spending. For state-level data, you would need separate data sources such as individual state transparency portals.

**What date range is supported?**
The earliest available data begins on 2007-10-01 (the start of federal fiscal year 2008). You can search any date range from that point to the present using the format "YYYY-MM-DD to YYYY-MM-DD."

**How are results sorted?**
Results are always sorted by award amount in descending order (largest first). For loan searches, results are sorted by loan face value. This means setting a small `maxResults` value gives you the biggest awards immediately.

**What is the difference between awarding agency and funding agency?**
The awarding agency is the federal agency that issues and manages the contract or grant. The funding agency provides the money. These are often the same, but in some cases (such as interagency agreements), the funding comes from a different agency than the one managing the award.

**Can I get results in CSV or Excel format?**
Yes. After the actor completes, click "Export" on the dataset page and choose CSV, Excel, JSON, or XML. The Apify API also supports `format=csv` and `format=xlsx` query parameters for programmatic access.

**How do I find the correct agency name?**
Visit [USAspending.gov](https://www.usaspending.gov) and browse the Agency page to find the exact official name. Common examples include "Department of Defense," "Department of Health and Human Services," "National Aeronautics and Space Administration," and "Department of Energy."

**Is this the same data as on USAspending.gov?**
Yes. This actor queries the same official USAspending.gov API that powers the website. The data is identical -- the actor simply provides it in a structured, machine-readable format with automated search and export capabilities.

***

### Related actors

| Actor | Description | Link |
|-------|-------------|------|
| SAM.gov Contract Monitor | Search active federal contract opportunities and solicitations on SAM.gov | [View](https://apify.com/ryanclinton/sam-gov-contract-monitor) |
| Grants.gov Federal Grant Search | Search active federal grant opportunities across all agencies | [View](https://apify.com/ryanclinton/grants-gov-search) |
| Congress Bill Search | Search US congressional bills and legislation by keyword, sponsor, or status | [View](https://apify.com/ryanclinton/congress-bill-search) |
| FEC Campaign Finance Search | Search Federal Election Commission data for campaign contributions and political spending | [View](https://apify.com/ryanclinton/fec-campaign-finance) |
| Federal Register Search | Search proposed rules, final rules, and notices in the Federal Register | [View](https://apify.com/ryanclinton/federal-register-search) |
| Congressional Stock Trade Tracker | Track stock transactions reported by members of the US Congress | [View](https://apify.com/ryanclinton/congress-stock-tracker) |
| OFAC Sanctions Search | Screen entities against the US Treasury OFAC sanctions list | [View](https://apify.com/ryanclinton/ofac-sanctions-search) |
| SEC EDGAR Filing Analyzer | Search and analyze SEC financial filings and corporate disclosures | [View](https://apify.com/ryanclinton/sec-edgar-filing-analyzer) |
| CFPB Consumer Complaints | Search consumer complaints filed with the Consumer Financial Protection Bureau | [View](https://apify.com/ryanclinton/cfpb-consumer-complaints) |
| FDIC Bank Data Search | Search FDIC bank financial data and institution information | [View](https://apify.com/ryanclinton/fdic-bank-search) |

# Actor input Schema

## `mode` (type: `string`):

What the run optimises for. 'search' (default) returns award rows + analytics. 'market' adds a market-scan digest answering 'should I care about this market?' (health score, trend, incumbents, gaining/losing share). 'contractor' adds a contractor-profile digest for the recipient you search (share, vulnerability, top agencies). 'monitor' is search + cross-run change tracking + historical market snapshots (set a watchlistName). 'discover' ignores the keyword and ranks a curated set of federal markets by spending growth ('where should I be looking?').

## `keyword` (type: `string`):

Search keyword across award descriptions (e.g. 'cybersecurity', 'renewable energy', 'healthcare'). Leave empty to search by recipient/agency/date only.

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

Additional keywords, matched as ANY (OR) by the USAspending API. Combined with the single Search Keyword above.

## `awardType` (type: `string`):

Type of federal spending award to search. Awards from different groups cannot be mixed in one API request — for multiple types use 'Award Types (multiple)' below, which runs each group and merges the results.

## `awardTypes` (type: `array`):

Search several award types in one run. Valid values: contracts, grants, loans, direct\_payments, other, idvs. Each type is fetched as its own API group, then merged and ranked together. Takes precedence over the single Award Type above.

## `dateRange` (type: `string`):

Filter by date range in format 'YYYY-MM-DD to YYYY-MM-DD' (e.g. '2024-01-01 to 2024-12-31'). Earliest supported: 2007-10-01.

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

Which date the Date Range filters on. 'action\_date' (default) = the award/transaction action date; 'date\_signed' = when the award was signed; 'last\_modified\_date' = last update; 'new\_awards\_only' = only brand-new awards in the window.

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

Maximum number of awards to return (API returns up to 100 per page). Across multiple award types, the merged top results are returned up to this cap.

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

Filter by awarding agency name (e.g. 'Department of Defense', 'Department of Energy'). Must be the exact official top-tier name unless 'Resolve agency name' is on.

## `resolveAgency` (type: `boolean`):

Resolve a loose agency name ('DoD', 'NASA') to its canonical top-tier name via the USAspending autocomplete endpoint before filtering. Any resolution is reported in the summary's resolutionWarnings. Costs one extra API call.

## `recipient` (type: `string`):

Search by recipient/contractor name (e.g. 'Lockheed Martin', 'Deloitte').

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

Filter by NAICS industry codes (e.g. '541512' Computer Systems Design Services). One or more 6-digit codes.

## `naicsSearch` (type: `array`):

Don't know the codes? Enter plain-language industry terms (e.g. 'cybersecurity', 'cloud') and the actor resolves them to NAICS codes via the autocomplete endpoint. Merged with any NAICS Codes above.

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

Filter by Product or Service Code (e.g. 'D399' IT and Telecom services). One or more codes.

## `pscSearch` (type: `array`):

Plain-language product/service terms resolved to PSC codes via the autocomplete endpoint. Merged with any PSC Codes above.

## `recipientStates` (type: `array`):

Filter by recipient location, by 2-letter US state code (e.g. 'VA', 'MD', 'CA').

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

Filter by where the work is performed, by 2-letter US state code.

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

Minimum award amount in dollars (e.g. 1000000 for $1M+).

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

Maximum award amount in dollars. Combine with the minimum to set an amount band.

## `sortBy` (type: `string`):

Order results by award amount (default) or recipient name.

## `sortOrder` (type: `string`):

Descending (largest/last first, default) or ascending.

## `outputProfile` (type: `string`):

How much detail to include on each award record. 'minimal' = decision-shaped headline (recipient, amount, size tier, agency, active flag, recompete signal, flags, link). 'standard' = the full record minus the long description. 'full' = every field including the complete description text. A run-level analytics summary record is always included regardless of profile.

## `recompeteWindowDays` (type: `integer`):

Contracts whose period of performance ends within this many days are flagged as recompete opportunities (recompeteSignal). Default 180.

## `includeExpiringOnly` (type: `boolean`):

Emit only awards inside the recompete window (expiring-soon or recompete-window). Suppressed awards are still counted in the summary analytics. Default off.

## `onlyFlagged` (type: `boolean`):

Emit only awards carrying at least one anomaly flag (e.g. amount\_above\_p95, ending\_soon, single\_recipient\_dominance). Suppressed awards are still counted in the summary analytics. Default off.

## `includeTrend` (type: `boolean`):

Also compute the federal spending trend for these filters across fiscal years (rising / falling / stable), added to the summary record. Costs one extra API call. Default off.

## `watchlistName` (type: `string`):

Name a watchlist to turn on cross-run monitoring. The actor remembers the awards and recipient shares from each run under this name; the next run tags each award with a changeType (new\_award / amount\_increased / amount\_decreased / contract\_extended / unchanged) and computes recipient share momentum. The first run is a baseline. Leave empty for a one-off search.

## `emitOnly` (type: `string`):

When monitoring is on, emit only awards of these change classes. 'all' (default), 'new' (only new\_award), 'changed' (amount/extension changes), or 'new\_or\_changed'. Suppressed awards are still tracked and counted. Ignored when no watchlist is set.

## Actor input object example

```json
{
  "mode": "search",
  "keyword": "cybersecurity",
  "awardType": "contracts",
  "dateType": "action_date",
  "maxResults": 25,
  "resolveAgency": false,
  "sortBy": "amount",
  "sortOrder": "desc",
  "outputProfile": "standard",
  "recompeteWindowDays": 180,
  "includeExpiringOnly": false,
  "onlyFlagged": false,
  "includeTrend": false,
  "emitOnly": "all"
}
```

# Actor output Schema

## `intelligence` (type: `string`):

Award rows with size tier, recompete signal, priority score and flags — the decision-first table.

## `expiring` (type: `string`):

Contracts ending inside the recompete window, with the incumbent and days remaining.

## `alerts` (type: `string`):

Awards carrying anomaly flags, sorted by priority score.

## `changes` (type: `string`):

New and changed awards vs the prior watchlist run, with amount deltas.

## `capture` (type: `string`):

Awards ranked by BD capture-worthiness (size + ending soon + competitive market).

## `discovery` (type: `string`):

Discover mode: candidate federal markets ranked by spending growth.

## `incumbents` (type: `string`):

Market mode: incumbents ranked by recompete vulnerability and at-risk value.

## `allItems` (type: `string`):

Every record (awards + summary) with all fields.

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

The run-level analytics record (concentration, top recipients, recompete pipeline) mirrored to the key-value store.

## `query` (type: `string`):

The resolved search filters that produced this run.

# 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 = {
    "keyword": "cybersecurity",
    "maxResults": 25,
    "recompeteWindowDays": 180
};

// Run the Actor and wait for it to finish
const run = await client.actor("ryanclinton/usaspending-search").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 = {
    "keyword": "cybersecurity",
    "maxResults": 25,
    "recompeteWindowDays": 180,
}

# Run the Actor and wait for it to finish
run = client.actor("ryanclinton/usaspending-search").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 '{
  "keyword": "cybersecurity",
  "maxResults": 25,
  "recompeteWindowDays": 180
}' |
apify call ryanclinton/usaspending-search --silent --output-dataset

```

## MCP server setup

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

```

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/duGhhKevB8g6WhyJC/builds/ocESUmXeXVgagE3qk/openapi.json