# Apify Usaspending (`4etverg/apify-usaspending`) Actor

Search public USAspending.gov federal awards for analysts, journalists, and contractors. Returns flat rows for contracts, grants, loans, and direct payments. No API key or login.

- **URL**: https://apify.com/4etverg/apify-usaspending.md
- **Developed by:** [Konstantin](https://apify.com/4etverg) (community)
- **Categories:** Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 saved 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/platform/actors/running/actors-in-store#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.gov Award Search

Search federal awards from [USAspending.gov](https://www.usaspending.gov/) and download them as a clean, flat dataset — one row per award, ready for a spreadsheet, CRM, or database.

### Why use this if the data is free?

USAspending.gov data is **public and free**. Its API needs no API key. This Actor does not sell exclusive data.

You pay for the packaging:

- **No API work.** You do not write pagination, award-type code maps, retries, or request bodies.
- **Plain-language filters.** Pick agency, date range, award categories (contracts, grants, loans, and so on), and optional recipient name — not raw USAspending code lists.
- **Flat rows.** Each award is one simple record with consistent field names, not nested API JSON.
- **Downloadable results.** Runs land in an Apify dataset you can export as JSON, CSV, or Excel, or pull into another workflow.

If you already maintain a production integration against `api.usaspending.gov`, you may not need this. If you want award lists without building that integration, this is the shortcut.

### Input (what you set)

| Field | What it does |
| --- | --- |
| `agencyName` | Optional federal agency name (e.g. `Department of the Treasury`). Leave blank for all agencies. |
| `agencyRole` | Treat the agency as **awarding** (default) or **funding**. |
| `startDate` / `endDate` | Optional date window. If both are omitted, the run uses the last 30 days. |
| `awardTypeGroups` | One or more of: `contracts`, `idvs`, `loans`, `grants`, `direct_payments`, `other_financial_assistance`. Omit to search all categories. |
| `recipientName` | Optional recipient name. The Actor resolves it through USAspending's recipient lookup and then filters awards server-side. |
| `recipientUei` | Optional recipient UEI. The Actor sends it to USAspending as a native recipient search filter. |
| `maxResults` | Cap on how many awards to save (default 1,000). |
| `pageSize` | Page size for API requests (default 100). |

### Output fields

Each saved dataset item has these fields (as emitted by the Actor):

| Field | Type | Description |
| --- | --- | --- |
| `internalId` | number | USAspending internal award id from the search response. |
| `awardId` | string | null | Public award identifier (e.g. contract or assistance id). |
| `recipientName` | string | null | Name of the recipient. |
| `awardAmount` | number | null | Award amount in dollars. |
| `startDate` | string | null | Period-of-performance start date (`YYYY-MM-DD`) when present. |
| `endDate` | string | null | Period-of-performance end date (`YYYY-MM-DD`) when present. |
| `awardType` | string | null | Award type label when the API returns one (often null for some contract rows). |
| `awardingAgency` | string | null | Awarding agency name. |
| `awardingSubAgency` | string | null | Awarding sub-agency name. |
| `fundingAgency` | string | null | Funding agency name. |
| `fundingSubAgency` | string | null | Funding sub-agency name. |
| `generatedInternalId` | string | null | USAspending generated internal id string. |
| `source` | object | Provenance: `endpoint`, `page`, `pageSize`, `awardTypeGroup`, `fetchedAt` (ISO timestamp). |

A run summary is also stored in the key-value store as `OUTPUT` and `SUMMARY` (status, counts, filters used, any warnings).

### Pricing

**$0.02 per successful run** plus **$0.001 per saved award row** (about **$1.00 per 1,000 rows**).

Examples: 10 rows ≈ $0.03; 100 rows ≈ $0.12; 1,000 rows ≈ $1.02.

### Use cases

#### 1. Government-contracting business development

Find recent contract awards for a target agency and export them for pipeline research.

**Example input**

```json
{
  "agencyName": "Department of the Treasury",
  "agencyRole": "awarding",
  "startDate": "2026-06-01",
  "endDate": "2026-07-27",
  "awardTypeGroups": ["contracts"],
  "maxResults": 50
}
```

**Sample output row** (from a live run of this input; one of the top results by award amount)

```json
{
  "internalId": 279026177,
  "awardId": "2032H521F00050",
  "recipientName": "AT&T ENTERPRISES, LLC",
  "awardAmount": 320206879.61,
  "startDate": "2020-12-23",
  "endDate": "2026-09-30",
  "awardType": null,
  "awardingAgency": "Department of the Treasury",
  "awardingSubAgency": "Internal Revenue Service",
  "fundingAgency": "Department of the Treasury",
  "fundingSubAgency": "Departmental Offices",
  "generatedInternalId": "CONT_AWD_2032H521F00050_2050_GS00Q17NSD3000_4732",
  "source": {
    "endpoint": "search/spending_by_award",
    "page": 1,
    "pageSize": 5,
    "awardTypeGroup": "contracts",
    "fetchedAt": "2026-07-27T20:43:03.196Z"
  }
}
```

#### 2. Lobbying and policy research

Track grants and direct payments tied to a named recipient over a calendar year.

**Example input**

```json
{
  "recipientName": "STATE OF CALIFORNIA EMPLOYMENT DEVELOPMENT DEPARTMENT",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "awardTypeGroups": ["grants", "direct_payments"],
  "maxResults": 25
}
```

**Sample output row** (from a live run of this input)

```json
{
  "internalId": 271710794,
  "awardId": "UI347022055A6",
  "recipientName": "STATE OF CALIFORNIA EMPLOYMENT DEVELOPMENT DEPARTMENT",
  "awardAmount": 729771187.85,
  "startDate": "2020-04-01",
  "endDate": "2025-06-30",
  "awardType": "GRANT",
  "awardingAgency": "Department of Labor",
  "awardingSubAgency": "Employment and Training Administration",
  "fundingAgency": "Department of Labor",
  "fundingSubAgency": "Employment and Training Administration",
  "generatedInternalId": "ASST_NON_UI347022055A6_1601",
  "source": {
    "endpoint": "search/spending_by_award",
    "page": 84,
    "pageSize": 5,
    "awardTypeGroup": "grants",
    "fetchedAt": "2026-07-27T20:44:41.259Z"
  }
}
```

Note: recipient searches resolve through USAspending's recipient endpoints and are applied server-side on the award search request. If the lookup finds no match, the Actor falls back to the raw recipient text.

#### 3. Journalism and investigative research

Pull a reproducible sample of federal awards for a story, filtered by agency and date window.

**Example input**

```json
{
  "agencyName": "Department of the Treasury",
  "agencyRole": "awarding",
  "startDate": "2026-07-01",
  "endDate": "2026-07-27",
  "awardTypeGroups": ["contracts", "grants", "direct_payments"],
  "maxResults": 100
}
```

**Sample output row** (from a live run of this input; results are sorted by award amount descending)

```json
{
  "internalId": 279028587,
  "awardId": "2032H525F00053",
  "recipientName": "SCIENCE APPLICATIONS INTERNATIONAL CORPORATION",
  "awardAmount": 152116836.84,
  "startDate": "2025-06-26",
  "endDate": "2027-06-19",
  "awardType": null,
  "awardingAgency": "Department of the Treasury",
  "awardingSubAgency": "Internal Revenue Service",
  "fundingAgency": "Department of the Treasury",
  "fundingSubAgency": "Departmental Offices",
  "generatedInternalId": "CONT_AWD_2032H525F00053_2050_2032H523A00010_2050",
  "source": {
    "endpoint": "search/spending_by_award",
    "page": 1,
    "pageSize": 5,
    "awardTypeGroup": "contracts",
    "fetchedAt": "2026-07-27T20:50:55.888Z"
  }
}
```

### Limitations

- **Search date coverage starts at 2007-10-01.** USAspending search warns that earlier data is outside this search endpoint (bulk download on the website or other API endpoints covers older periods).
- **Recipient name and UEI filters are native.** The Actor resolves recipient names through USAspending's recipient lookup when needed, then sends `recipient_search_text` to the award search API. Sparse recipients fail fast instead of being scanned page by page.
- **Award categories map to official codes.** Choosing e.g. `contracts` expands to the live USAspending contract type codes; you do not need to supply those codes yourself.
- **Some fields may be null.** For example, `awardType` is often null on contract search rows even when amount and agencies are present — that reflects the API response, not a silent drop.
- **Default window is 30 days** if you omit both start and end dates.
- **Transient API failures** are retried with backoff. If a later page still fails, rows already saved are kept and the run summary reports a partial failure.
- Results are ordered by **award amount descending** within each award-type group the Actor walks.

### How a run works

1. You set filters in the Actor input (or via API).
2. The Actor calls the public USAspending award search endpoint, page by page.
3. Matching awards are written to the default dataset as they arrive.
4. You download the dataset (JSON / CSV / Excel) or pass it to another Actor or integration.

Data source: [USAspending.gov API](https://api.usaspending.gov/) (`POST /api/v2/search/spending_by_award/`).

# Actor input Schema

## `agencyName` (type: `string`):

Optional. Enter a federal agency name such as 'Department of the Treasury'. Leave blank to search across all agencies.

## `agencyRole` (type: `string`):

Choose whether the agency should be treated as the awarding agency or the funding agency.

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

Optional. Filter to awards starting on or after this date. USAspending search currently reaches back to 2007-10-01.

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

Optional. Filter to awards ending on or before this date.

## `awardTypeGroups` (type: `array`):

Choose one or more plain-language award categories. The Actor expands them to the underlying USAspending codes.

## `recipientName` (type: `string`):

Optional. Filter the saved dataset to awards whose recipient name contains this text.

## `recipientUei` (type: `string`):

Optional. Filter the saved dataset to awards whose recipient UEI contains this text.

## `pageSize` (type: `integer`):

How many awards to ask USAspending for on each request. Smaller pages are gentler on the API; larger pages use fewer requests.

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

Stop after saving this many awards. Use a lower number for quick checks or raise it for larger exports.

## Actor input object example

```json
{
  "agencyName": "Department of the Treasury",
  "agencyRole": "awarding",
  "startDate": "2026-06-27",
  "endDate": "2026-07-27",
  "awardTypeGroups": [
    "contracts",
    "grants",
    "direct_payments"
  ],
  "recipientName": "STATE OF CALIFORNIA EMPLOYMENT DEVELOPMENT DEPARTMENT",
  "pageSize": 100,
  "maxResults": 1000
}
```

# Actor output Schema

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

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

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

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "agencyName": "Department of the Treasury",
    "startDate": "2026-06-27",
    "endDate": "2026-07-27",
    "awardTypeGroups": [
        "contracts",
        "grants",
        "direct_payments"
    ],
    "recipientName": "STATE OF CALIFORNIA EMPLOYMENT DEVELOPMENT DEPARTMENT",
    "recipientUei": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("4etverg/apify-usaspending").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 = {
    "agencyName": "Department of the Treasury",
    "startDate": "2026-06-27",
    "endDate": "2026-07-27",
    "awardTypeGroups": [
        "contracts",
        "grants",
        "direct_payments",
    ],
    "recipientName": "STATE OF CALIFORNIA EMPLOYMENT DEVELOPMENT DEPARTMENT",
    "recipientUei": "",
}

# Run the Actor and wait for it to finish
run = client.actor("4etverg/apify-usaspending").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "agencyName": "Department of the Treasury",
  "startDate": "2026-06-27",
  "endDate": "2026-07-27",
  "awardTypeGroups": [
    "contracts",
    "grants",
    "direct_payments"
  ],
  "recipientName": "STATE OF CALIFORNIA EMPLOYMENT DEVELOPMENT DEPARTMENT",
  "recipientUei": ""
}' |
apify call 4etverg/apify-usaspending --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=4etverg/apify-usaspending",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/QJ42Yo9F9PKjGCtSO/builds/QvLN5JLygqqgzvQU9/openapi.json