Nexus Tools / Data guides

US federal awards as JSON or CSV: the USAspending API, its 10,000-result window, a Python example and a free sample

How to pull federal contract and grant awards from USAspending yourself, which limits and errors to expect (including a type-code change that started this month), and when a normalized feed is worth paying for.

Updated: November 2026. API behaviour below was tested live on 5 November 2026.

The short version

• USAspending.gov is the US government's public record of federal spending: contracts, grants, loans and other assistance, one record per award. Its API is free, needs no key and answers JSON. The award search is a single POST endpoint.
• The things that bite: 100 rows per page and a 10,000-result window, one award category per request (mixing types gives HTTP 422), a sort field that must also be in fields, a Department of Defense data lag of about 90 days, and, new this month, assistance award type codes that changed on 1 October 2026.
• If you want one flat schema across categories, a shared format with EU, UK and SAM.gov notices and no code to maintain, we run an Apify Actor for that. A real sample of its output is at the bottom, free to download.

1. The USAspending API

Documentation: api.usaspending.gov/docs/endpoints. The API contracts live in the open-source repository fedspendingtransparency/usaspending-api. The base URL is https://api.usaspending.gov, anonymous, JSON in and out. We found no documented rate limit and no rate-limit headers; calls take 1.5 to 5 seconds, so pace yourself anyway.

Main endpoints we used:

Limits we hit, with the exact errors

• limit maximum is 100. limit: 101 returns HTTP 422 with Field 'limit' value '101' is above max '100'.
• The 10,000-result window. On a query with more than 10,000 matches, hasNext turns false at page 100. Pages after that were still served in our test (page 101 returned 100 rows with hasNext: false), but that is undocumented behaviour. The reliable approach is to split the date range until each window holds fewer than 10,000 awards, checking the count first. A normal week is 10,000 to 50,000 contract actions (a week in late October 2026 had 11,159 contracts and 1,600 IDVs), so you will need windows for "everything".
• One award category per request. Mixing contract and grant codes returns HTTP 422: 'award_type_codes' must only contain types from one group. The groups are contracts (A, B, C, D), idvs (IDV_*), grants (02 to 05, and F001, F002), loans (07, 08, F003, F004), other_financial_assistance (06, 10, F006, F007) and direct_payments (09, 11, -1, F005, F008 to F010). The error body lists them all.
• The sort field must be in fields. Sorting by Award Amount without requesting it returns HTTP 400: Sort value 'Award Amount' not found in requested fields.
• Earliest date is 2007-10-01. A start date before that returns HTTP 422 (start_date cannot be earlier than '2007-10-01'). For older data the API points to the bulk download endpoints.
• "Action Date" is not a usable field. Asking for it returned null in every row. The practical "newest" fields are Last Modified Date (the latest update to the award record) and Base Obligation Date (when the base award was signed).

What "date" means: the date_type trap

time_period takes a date_type: action_date (the default: any transaction in the window, so it also returns modifications of awards signed years ago), new_awards_only, date_signed or last_modified_date. If you want "new contracts this week", use new_awards_only, otherwise old contracts keep reappearing every time they are modified.

The Department of Defense lag

DoD contract data is published with a delay of about 90 days, so DoD barely appears in recent windows. Counts of new DoD contract awards from the count endpoint on 5 November 2026:

For the same last week, all agencies together had 7,569 new contract awards. So a "last 7 days" run is a civilian-agency picture, and anything you compute about total federal obligations is biased unless you account for this. Check the window against awards/last_updated and against DoD separately.

New in October 2026: assistance type codes changed

This one costs you silently. The award-type groups returned by the API now include F001 to F010 codes, and awards made since 1 October 2026 use them. Counting 22 October to 5 November: ["F001","F002"] returned 1,599 grants and ["F003","F004"] 2,946 loans, while the old codes ["02","03","04","05"] and ["07","08"] returned zero. For September 2026 it is the other way round (20,389 grants under the old codes). Contracts and IDVs keep their A to D and IDV_* codes. If your code has the old list hard-coded, include both lists in the same request (they are in the same group, so no 422).

Field shapes

• Fields differ by category: loans have Loan Value and Subsidy Cost and return Award Amount: null; grants have Assistance Listings; IDVs have Last Date to Order.
• Award Amount is the total obligated so far, not the contract ceiling (the ceiling and options value are in the detail endpoint).
• NAICS, PSC, Recipient Location and Primary Place of Performance are objects, not strings.
• Descriptions are upper case, as published. The detail endpoint also lists executive officers with their pay; you do not need it for market data and it is personal data.

2. DIY: contract awards to CSV in Python

This script counts first, then pages through the newest contract actions of the last week with an obligation of at least 250,000 USD, and writes a CSV. Tested on 5 November 2026: the count said 1,949 contracts, the loop (limited to 3 pages for the demo) wrote 300 rows. It needs pip install requests.

import csv
import time
from datetime import date, timedelta

import requests

BASE = "https://api.usaspending.gov/api/v2"
FIELDS = ["Award ID", "Recipient Name", "Recipient UEI", "Awarding Agency", "Awarding Sub Agency",
          "Description", "Award Amount", "Base Obligation Date", "Last Modified Date",
          "NAICS", "PSC", "generated_internal_id"]          # the sort field must be in this list
FILTERS = {
    "award_type_codes": ["A", "B", "C", "D"],               # ONE group only: contracts (mixing groups = HTTP 422)
    "time_period": [{"start_date": (date.today() - timedelta(days=7)).isoformat(),
                     "end_date": date.today().isoformat(),
                     "date_type": "action_date"}],
    "award_amounts": [{"lower_bound": 250000}],
}


def post(path, body):
    for attempt in range(5):
        r = requests.post(f"{BASE}{path}", json=body, timeout=60)
        if r.status_code in (429, 500, 502, 503, 504):
            time.sleep(2 ** attempt)
            continue
        r.raise_for_status()                                 # 422 = bad limit or mixed award groups
        return r.json()
    raise RuntimeError("USAspending unavailable")


counts = post("/search/spending_by_award_count/", {"filters": FILTERS})["results"]
print("matches per category:", counts)                      # check this BEFORE paging: > 10,000 needs date windows

rows, page = [], 1
while page <= 3:                                             # 3 pages x 100 rows for the demo; hasNext ends at page 100
    data = post("/search/spending_by_award/", {
        "filters": FILTERS, "fields": FIELDS, "sort": "Last Modified Date", "order": "desc",
        "limit": 100, "page": page})                         # limit above 100 = HTTP 422
    rows += data["results"]
    if not data["page_metadata"]["hasNext"]:
        break
    page += 1
    time.sleep(0.5)                                          # be polite; no rate limit is documented

with open("usaspending_awards.csv", "w", newline="", encoding="utf-8") as f:
    w = csv.DictWriter(f, fieldnames=FIELDS, extrasaction="ignore")
    w.writeheader()
    for r in rows:
        r["NAICS"] = (r.get("NAICS") or {}).get("code")      # NAICS and PSC come back as objects
        r["PSC"] = (r.get("PSC") or {}).get("code")
        w.writerow(r)
print(len(rows), "awards")

3. When the Actor saves time

For a one-off export the script above is enough and free. The Apify Actor USAspending Federal Awards (by Nexus Scrapers) wraps the same official API. It pays off when you would otherwise maintain that code:

• One normalized schema shared with our TED, UK and SAM.gov Actors: awardInfo with winners and awarded value as {amount, currency}, ISO country codes, dates as YYYY-MM-DD, missing values as null. USAspending-specific data (agency codes, recipient UEI, NAICS and PSC with descriptions, assistance listings, period of performance) sits in extra usa* keys.
• Windowing beyond 10,000 results: the Actor counts, splits the date range and reads newest first, up to 50,000 results per run, with retries and polite pacing.
• Filters as plain inputs: category, award type codes, keyword, awarding agency, sub-agency, recipient name or UEI, NAICS, PSC, state, amount range, date window and date type.
• Optional detail enrichment (competition, set-aside, parent contract, number of offers) with one extra call per award, and no officer names or compensation.
• Scheduling and integrations through Apify: daily runs into Slack, e-mail, Google Sheets or a webhook; export as JSON, CSV or Excel; API and MCP access.

Pricing is pay per result; the Actor page shows the current price.

Limits: one category per run (the API's rule), no sub-awards, no recipient profiles, no bulk-archive downloads for full-year dumps, and the Department of Defense lag above applies to the Actor too. Foreign places of performance are not filterable. The Actor's assistance categories were updated on 5 November 2026 to send the new F-codes as well as the old ones; contracts and IDVs were never affected.

4. Real sample: 20 normalized records

These 20 records were produced on 5 November 2026 by running the Actor's own code locally on live API responses (no Apify platform involved): 14 contract awards of at least 250,000 USD (at most two per agency, last modified on 2 November 2026) and 6 grants or cooperative agreements from two agencies, last modified on 3 November 2026, all signed between 2022 and 2025 (a modification refreshes the modified date). They are the first matches in that order, not hand-picked for quality. Loans are not included, because recipients of small-business loans are often sole traders named after a person. A scrub pass over every text field found no e-mail address or phone number to remove.

Download: sample.json (full records, UTF-8) and sample.csv (flattened, lists joined with | , opens in Excel). Free to use under the notes in section 5. Note that "Obligated" is money committed so far, not the contract ceiling.

One contract award record, trimmed to the main fields:

{
  "sourceId": "CONT_AWD_693JF721F000078_6938_47QRAA19D0085_4732",
  "url": "https://www.usaspending.gov/award/CONT_AWD_693JF721F000078_6938_47QRAA19D0085_4732",
  "noticeType": "contract-award",
  "noticeTypeCode": "C",
  "contractNature": "services",
  "title": "TEMPORARY FULL-TIME CONTRACTOR SUPPORT FOR THE MARITIME ADMINISTRATION OFFICE OF BUDGET POSITION TITLE: BUDGET & PROGRAM ANALYST NUMBER OF POSITIONS: THREE (3)…",
  "buyer": {
    "name": "Department of Transportation",
    "country": "US",
    "city": null,
    "nutsCode": null,
    "buyerType": "central-government"
  },
  "publicationDate": "2026-11-02",
  "awardInfo": {
    "winners": [
      {
        "name": "GUIDEHOUSE INC.",
        "country": "US"
      }
    ],
    "awardedValue": {
      "amount": 4777508.57,
      "currency": "USD"
    },
    "awardDate": "2021-09-30"
  },
  "placeOfPerformance": {
    "country": "US",
    "city": "WASHINGTON",
    "nutsCode": null
  },
  "usaAwardId": "693JF721F000078",
  "usaAwardCategory": "contracts",
  "usaAwardType": "DELIVERY ORDER",
  "usaAwardingSubAgency": "Maritime Administration",
  "usaRecipientUei": "N9NJK877QJK9",
  "usaNaics": {
    "code": "541611",
    "description": "ADMINISTRATIVE MANAGEMENT AND GENERAL MANAGEMENT CONSULTING SERVICES"
  },
  "usaPsc": {
    "code": "R408",
    "description": "SUPPORT- PROFESSIONAL: PROGRAM MANAGEMENT/SUPPORT"
  },
  "usaPeriodOfPerformance": {
    "startDate": "2021-09-30",
    "endDate": "2026-11-28",
    "lastDateToOrder": null
  },
  "usaLastModified": "2026-11-02 22:03:29"
}

5. Data licence and terms

USAspending.gov is the official US federal spending website, run under the DATA Act. We found no licence or terms statement on api.usaspending.gov itself, and the site is a JavaScript application, so we could not read its notices in a script. What we could verify: the API's source repository is released under CC0 1.0, and the records are federal spending data published for public reuse. Works created by US federal employees as part of their duties are in the public domain under 17 U.S.C. 105, but data about awards also comes from recipients and agencies' systems; if your use is commercial or you republish at scale, read the About page and the site's data notes, and credit "USAspending.gov" as the source. This is a summary, not legal advice.

Personal data: recipients are mostly organisations, but individuals and sole traders can be recipients (loans, some assistance). The Actor does not copy street addresses or executive officer names and pay; our sample contains organisations only.

Links

• USAspending Federal Awards Actor on Apify
• Official USAspending API documentation
• The companion guide for open opportunities: SAM.gov
• The same kind of guide for EU tenders (TED)