USASpending API Guide (2026)

USASpending.gov is the US Treasury's public transparency site for all federal spending. Under the hood it pulls from FPDS-NG (Federal Procurement Data System) for contracts, from agency grants systems for grants and loans, and from FSRS reporting for sub-awards. It exposes this data through a JSON REST API that anyone can hit without an account.

What it covers:

• Contracts back to FY 2008 (prime awards). This is the piece that overlaps with SAM.gov.
• Grants, loans, direct payments, insurance. If a federal dollar moved, it shows up here.
• Sub-awards (subcontracts and sub-grants above $30K, from FSRS self-reporting by primes).
• Recipient profiles with parent-company linkage, business categories, and geographic breakdowns.

What it is not:

• Not a source of current opportunities. USASpending is historical. For active solicitations use SAM.gov.
• Not real-time. Data lags SAM.gov by 2-4 weeks (SAM.gov to FPDS to USASpending).
• Not a replacement for FPDS-NG's raw feed if you need transaction-level detail the search endpoints do not expose.

USASpending is genuinely free. No account, no API key, no CAPTCHA. Base URL: https://api.usaspending.gov. Every request is either a GET for a single resource or a POST with a JSON filter body for searches. There is no header-based auth. CORS is open; you can hit it from a browser, curl, or server-side.

Rate limits: not officially published. Tested 20 concurrent workers running 60 search requests back-to-back (April 2026): zero 429s, zero 504s, median latency ~1.6s. In practice the API tolerates whatever pace you throw at it in reasonable amounts. Still back off exponentially on any transient 429/502/503/504.

Field names switch between endpoints.

The search endpoints use capitalized, spaced field names ("Award ID", "Recipient Name", "Recipient UEI", "Award Amount") in the fields array, and the same keys show up in the response. But recipient_id, uei, generated_internal_id on the same response are lowercase snake_case. Other endpoints (the detail endpoint, the category endpoints) use lowercase snake_case throughout. Read an example response before guessing.

spending_by_award returns NULL for the fields you actually want.

NAICS, PIID, obligation, date signed, extent competed. All NULL. See the endpoint section above. You cannot fix this by changing your fields array; the API does not populate them on this endpoint. Fetch awards individually for those fields or use spending_by_transaction.

Sort and order are required on spending_by_award.

Missing them returns a 400 with a list of valid sort keys. Common pick: "sort": "Award Amount", "order": "desc".

recipient_id is not UEI.

recipient_id is a USASpending-internal hash like 6cf5fb1b-4988-d087-5dc1-70939d8fc6c4-C. Three possible suffixes expose different aggregation views of the same entity: -C (child or direct entity, always present), -P (parent company view, only exists when the entity has a corporate parent), -R (recognized aggregate across related identifiers). A given UEI maps to exactly one -C recipient_id, but a corporate parent may have many. For stable cross-system matching use Recipient UEI or uei, not recipient_id.

Pagination is page + limit, not offset.

Pass "page": 1 (1-indexed), not "offset": 0. Max 100 per page on most endpoints. Check page_metadata.hasNext in the response to know when you are done.

Award type codes are opaque letters and digits.

A, B, C, D = contracts (BPA, purchase order, definitive contract, etc.). 02, 03, 04, 05 = grants. Omit award_type_codes and you will pull everything including loans and grants. Almost always you want ["A","B","C","D"].

Time period dates are strings, not ISO datetimes.

Format: "start_date":"2024-01-01". Earliest allowed is 2007-10-01 (start of FY 2008). The API returns a warning in the messages array if you request earlier.

The search endpoints are slow at high offsets.

Beyond page ~50 (5,000 records), response time climbs significantly. For bulk, use the download endpoint.

Sort field must appear in your fields array.

If you pass "sort": "Award Amount" but omit "Award Amount" from fields, the API returns a 400: "Sort value 'Award Amount' not found in requested fields". Always include the sort field among the fields you request.

Sub-award endpoints are a parallel universe.

Searching sub-awards uses the same spending_by_award endpoint but adds "subawards": true to the request body. Valid fields switch to sub-award variants: "Sub-Award ID", "Sub-Award Amount", prime_award_generated_internal_id. Sub-award data comes from FSRS self-reporting by prime contractors and is incomplete (some primes do not report; accuracy varies).

If you already have SAM.gov award data and want to enrich it, or vice versa, the match key is:

To build a generated_internal_id from a SAM award_number: the format is CONT_AWD_{award_number}_{agency_toptier_code}_-NONE-_-NONE-. Easier route: search spending_by_award with a keyword filter equal to the award number.

SAM.gov's Award Notice feed is what contracting officers publish on the public opportunity portal. USASpending draws from FPDS, which captures more contract actions. Measured against our ingested SAM Award Notices and USASpending corpus in April 2026:

• Overlap: 4,840 distinct UEIs appear in both sources.
• USASpending-only: 22,949 UEIs have contracts in USASpending that never show up as a SAM Award Notice in our dataset.
• SAM-only: 6,286 UEIs appear in SAM Award Notices but have no matching USASpending record yet (these are mostly recent awards still inside the 2-4 week propagation lag).

Why the USASpending-only delta exists:

• Task orders under IDIQs often do not generate a separate SAM Award Notice. They show up in FPDS (and USASpending) as new contract actions, but not as public notices.
• Contract modifications (increases, option exercises) are in FPDS but almost never post as standalone SAM notices.
• Agency-reporting lag. Some contract offices post to FPDS but not to SAM's opportunity feed.

If completeness matters (market research, full competitive mapping, due diligence), you need both sources.

Fields you already get from SAM Award Notices (no reason to fetch from USASpending):

• Recipient name, UEI, address
• Award amount
• Awarding agency, sub-agency
• NAICS, PSC (in SAM), solicitation number, set-aside type

Fields you only get from USASpending (worth the enrichment):

• Total obligation vs award ceiling. These differ. Ceiling is what was authorized; obligation is what actually got spent. Meaningful gap for IDIQ and cost-plus contracts.
• Business categories. Whether the recipient qualifies as Small Business, WOSB (Women-Owned), HUBZone, SDVOSB (Service-Disabled Veteran-Owned), 8(a), etc. Self-certified but audited.
• Parent company name and UEI. Important when a "small" subsidiary is owned by a large parent.
• Extent competed. Sole Source, Full and Open, Competed Under SAP, etc. Tells you whether the award was actually contested.
• Type of contract pricing. Firm Fixed Price, Cost Plus Fixed Fee, Time and Materials, etc.
• Sub-awards. Who the prime subcontracted work to (from FSRS reporting).
• Pre-2024 history. USASpending has 15+ years of data. SAM.gov's public award feed is much shorter and less reliable for older contracts.

1. Look up a recipient's UEI by company name

import requests

def find_uei(company_name):
    r = requests.post(
        "https://api.usaspending.gov/api/v2/search/spending_by_award/",
        json={
            "filters": {
                "recipient_search_text": [company_name],
                "award_type_codes": ["A","B","C","D"],
                "time_period": [{"start_date":"2022-01-01","end_date":"2026-12-31"}],
            },
            # "Award Amount" must be in fields because we sort by it
            "fields": ["Recipient Name", "Recipient UEI", "Award Amount"],
            "sort": "Award Amount",
            "order": "desc",
            "limit": 5,
        },
    )
    r.raise_for_status()
    return [(row["Recipient Name"], row["Recipient UEI"]) for row in r.json()["results"]]

print(find_uei("Lockheed Martin"))

2. Pull a contractor's full award history

Two steps because spending_by_award is thin. Step 1 gets the list. Step 2 enriches each award with NAICS, PSC, obligation, business categories.

import requests
import time

UEI = "FYHNA5WC8XD7"  # example

# Step 1: paginate spending_by_award
awards = []
page = 1
while True:
    r = requests.post(
        "https://api.usaspending.gov/api/v2/search/spending_by_award/",
        json={
            "filters": {
                "recipient_search_text": [UEI],
                "award_type_codes": ["A","B","C","D"],
                "time_period": [{"start_date":"2008-10-01","end_date":"2026-12-31"}],
            },
            "fields": ["Award ID","Recipient UEI","Award Amount","Start Date","Awarding Agency"],
            "sort": "Award Amount",
            "order": "desc",
            "page": page,
            "limit": 100,
        },
    )
    data = r.json()
    awards.extend(data["results"])
    if not data["page_metadata"]["hasNext"]:
        break
    page += 1
    time.sleep(0.3)

# Step 2: enrich with detail endpoint
enriched = []
for a in awards[:50]:
    gid = a["generated_internal_id"]
    d = requests.get(f"https://api.usaspending.gov/api/v2/awards/{gid}/").json()
    enriched.append({
        **a,
        "naics": d.get("latest_transaction_contract_data", {}).get("naics"),
        "psc": d.get("latest_transaction_contract_data", {}).get("product_or_service_code"),
        "total_obligation": d.get("total_obligation"),
        "business_categories": d.get("recipient", {}).get("business_categories", []),
        "parent_recipient_name": d.get("recipient", {}).get("parent_recipient_name"),
        "extent_competed": d.get("latest_transaction_contract_data", {}).get("extent_competed"),
    })
    time.sleep(0.25)

print(f"Fetched {len(enriched)} enriched awards")

3. Size a market: top 20 contractors in a NAICS

import requests

def top_recipients_in_naics(naics, start, end, limit=20):
    r = requests.post(
        "https://api.usaspending.gov/api/v2/search/spending_by_category/recipient/",
        json={
            "filters": {
                "naics_codes": {"require": [naics]},
                "time_period": [{"start_date": start, "end_date": end}],
            },
            "limit": limit,
        },
    )
    return r.json()["results"]

for row in top_recipients_in_naics("541512", "2024-01-01", "2026-12-31"):
    print(f"${row['amount']/1e6:>10,.1f}M  {row['uei']}  {row['name']}")

4. Match a SAM award_number to USASpending

import requests

def find_in_usaspending(sam_award_number):
    r = requests.post(
        "https://api.usaspending.gov/api/v2/search/spending_by_award/",
        json={
            "filters": {
                "keywords": [sam_award_number],
                "award_type_codes": ["A","B","C","D"],
                "time_period": [{"start_date":"2020-01-01","end_date":"2026-12-31"}],
            },
            "fields": ["Award ID","Recipient Name","Recipient UEI","Award Amount"],
            "sort": "Award Amount",
            "order": "desc",
            "limit": 5,
        },
    )
    results = r.json()["results"]
    if not results:
        return None  # May just be too new (2-4 week USASpending lag)
    return results[0]["generated_internal_id"]

# Then fetch full detail
gid = find_in_usaspending("FA8620-25-C-0012")
if gid:
    detail = requests.get(f"https://api.usaspending.gov/api/v2/awards/{gid}/").json()

Do I need to register for USASpending?
No. The API is completely open. No account, no key, no CORS restrictions.

What's the actual rate limit?
Not published. In an April 2026 test, 20 concurrent workers issuing 60 search requests back-to-back hit zero 429s or 504s; median latency held at ~1.6 seconds. Treat that as the floor, not a guarantee. Back off exponentially on any transient 429/502/503/504.

Why does the same company appear with multiple recipient_id values?
USASpending assigns recipient_id at the parent, child, and recognized-entity levels. A corporate parent has one recipient_id; each subsidiary has its own. The -P / -C / -R suffix tells you which level. Match on Recipient UEI for stable identity across the hierarchy.

Why is my SAM.gov contract missing from USASpending?
Most likely it was awarded in the last 2-4 weeks and has not propagated yet. Retry after a month. If it is still missing, the contract action may not have been reported to FPDS (rare but happens with certain agency systems).

Can I get all award data for an agency in one request?
Use the bulk download endpoint (POST /api/v2/download/awards/) with an agency filter. The paginated search endpoints top out at 10,000 records per query (practical limit).

Does USASpending include classified contracts?
No. Classified contracts and certain national security work do not appear in FPDS and therefore not in USASpending.

Why do obligation totals not match the award amount?
Award amount is usually the ceiling (the most the government could spend). Total obligation is what has actually been committed as of the record's date. They converge as a contract completes; they diverge most for IDIQ, cost-plus, and long-running option-year contracts.

Does the API support GraphQL?
No. JSON REST only. The search endpoints use POST with a filter body; resource endpoints use GET.

Can I search by solicitation_identifier?
The filter accepts it, but since spending_by_award returns NULL for this field, your results rarely match. Match on keywords with the award number (PIID) instead, then read solicitation_identifier from the detail endpoint.

Is there an official Python client?
No. Plain requests works fine. Community clients exist on PyPI (search "usaspending") but most are incomplete.

USASpending is the correct free source for historical federal contract data. For live opportunities, use SAM.gov. For programmatic contractor research with peer analysis and aggregated profiles, our GovCon API collapses multi-step USASpending workflows into one call.

Last updated: April 2026 · How to research a federal contractor · SAM.gov API guide · Questions