USASpending APIusaspending.gov ↗
Access US federal government spending data via the USASpending.gov API. Search awards, contracts, subawards, agencies, and recipients with 6 endpoints.
What is the USASpending API?
This API exposes 6 endpoints covering US federal government spending data from USASpending.gov, including contracts, grants, subawards, and agency budget authority. The search_awards endpoint accepts keyword and structured filters to return paginated award records with recipient names, award amounts, and IDs. The get_award_details endpoint retrieves full award records including period of performance, funding agency hierarchy, and recipient business categories.
curl -X POST 'https://api.parse.bot/scraper/5b0e32c7-a0f5-44e5-b985-35a41a088f63/search_awards' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"filters": "{\"keywords\": [\"Salesforce\"]}",
"keywords": "Salesforce"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace usaspending-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: USASpending SDK — bounded, re-runnable; every call capped."""
from parse_apis.USASpending_gov_Data_API import USASpending, SpendingCategory, AgencySortField, SortOrder, AwardNotFound
client = USASpending()
# List top agencies by budget authority
for agency in client.toptier_agencies.list(sort=AgencySortField.BUDGET_AUTHORITY_AMOUNT, order=SortOrder.DESC, limit=3):
print(agency.agency_name, agency.budget_authority_amount, agency.abbreviation)
# Search for contract awards related to Salesforce
award = client.award_summaries.search(keywords="Salesforce", limit=1).first()
try:
detail = award.details()
print(detail.description, detail.total_obligation)
print(detail.recipient.recipient_name)
print(detail.period_of_performance.start_date, detail.period_of_performance.end_date)
except AwardNotFound as e:
print("award gone:", e.award_id)
# Search subawards
for sub in client.subawards.search(keywords="Salesforce", limit=3):
print(sub.prime_award_id, sub.subawardee_name, sub.subaward_amount)
# Spending by category
for item in client.spending_by_categories.search(category=SpendingCategory.FUNDING_AGENCY, limit=3):
print(item.name, item.amount, item.code)
# Find recipients matching a name
for match in client.recipient_matches.search(search_text="Microsoft", limit=3):
print(match.recipient_name, match.uei)
print("exercised: toptier_agencies.list, award_summaries.search, award.details, subawards.search, spending_by_categories.search, recipient_matches.search")
Search for government awards with advanced filtering. Returns paginated results of contracts and other award types. Supports keyword search and complex filter objects including time_period, award_type_codes, and agencies. If award_type_codes is not specified in filters, defaults to contracts (A, B, C, D).
| Param | Type | Description |
|---|---|---|
| filters | object | JSON object of filters including keywords, time_period, award_type_codes, agencies, etc. If award_type_codes is not specified, defaults to contracts (A, B, C, D). |
| keywords | string | Comma-separated search keywords to filter awards by (e.g. 'Salesforce' or 'Microsoft,Amazon'). Applied as keyword filter if no keywords are present in the filters object. |
{
"type": "object",
"fields": {
"results": "array of award summary objects containing internal_id, Award ID, Recipient Name, Award Amount, generated_internal_id",
"page_metadata": "object with page, hasNext, last_record_unique_id, last_record_sort_value",
"spending_level": "string indicating the spending level"
},
"sample": {
"data": {
"results": [
{
"Award ID": "W91ZLK23F0033",
"internal_id": 350571756,
"Award Amount": 214096.6,
"Recipient Name": "CARAHSOFT TECHNOLOGY CORP",
"generated_internal_id": "CONT_AWD_W91ZLK23F0033_9700_W52P1J20D0042_9700"
}
],
"page_metadata": {
"page": 1,
"hasNext": true,
"last_record_unique_id": 349975873,
"last_record_sort_value": "W912JM25FA023"
},
"spending_level": "awards"
},
"status": "success"
}
}About the USASpending API
Award Search and Detail
The search_awards endpoint accepts a filters object supporting keywords, time_period, award_type_codes, and agencies parameters. Results are paginated via page_metadata which includes hasNext, last_record_unique_id, and last_record_sort_value for cursor-style iteration. Each result exposes generated_internal_id, which feeds directly into get_award_details to retrieve the full award record. That detail response includes recipient (with recipient_uei, location, and business_categories), funding_agency and awarding_agency (each with toptier_agency and subtier_agency), total_obligation, and period_of_performance dates.
Subawards and Category Spending
The search_subawards endpoint returns subcontracts and subgrants under prime awards. Filters include prime_award_id, prime_recipient_name, and subawardee_name, allowing drill-down from a prime award into its sub-recipients. The search_spending_by_category endpoint groups spending totals by a chosen category — accepted values include awarding_agency, recipient, county, state_territory, and others — returning ranked name, id, code, and amount fields. A default one-year time_period filter is applied automatically when none is provided.
Agencies and Recipients
The list_agencies endpoint returns all federal toptier agencies with budget_authority_amount, percentage_of_total_budget_authority, and agency_slug for the current active fiscal year and quarter. Results are sortable by agency_name or budget_authority_amount. The search_recipients endpoint is an autocomplete lookup that returns recipient_name, recipient_level, uei, and duns identifiers — useful for resolving exact recipient strings before constructing award search filters.
The USASpending API is a managed, monitored endpoint for usaspending.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when usaspending.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official usaspending.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Identify all federal contracts awarded to a specific company by filtering
search_awardswith the company name as a keyword. - Build a federal budget dashboard using
list_agenciesto display each agency'sbudget_authority_amountand share of total budget. - Audit subcontracting relationships by querying
search_subawardswith aprime_award_idto list all subawardees under a specific prime contract. - Map federal spending by geography using
search_spending_by_categorywithcategoryset tostate_territoryorcounty. - Resolve a recipient's UEI before searching awards by running an autocomplete lookup against
search_recipientsfor a company name. - Track agency-level contract spending trends by filtering
search_spending_by_categorybyawarding_agencyover customtime_periodranges. - Pull full contract terms including
period_of_performanceandtype_descriptionfor a known award usingget_award_details.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does USASpending.gov have an official developer API?+
What does `search_awards` return and how do I paginate through results?+
search_awards returns an array of award summary objects, each containing Award ID, Recipient Name, Award Amount, and generated_internal_id. The page_metadata object in each response includes hasNext (boolean), last_record_unique_id, and last_record_sort_value, which you pass on subsequent requests to step through additional pages.What award fields does `get_award_details` expose that `search_awards` does not?+
get_award_details returns the full award record including recipient.business_categories, recipient.location, the complete funding_agency and awarding_agency hierarchies (toptier and subtier), description, type_description, and all three period_of_performance dates. search_awards returns only summary fields sufficient for listing and linking.Does the API expose individual spending transactions or contract line items beneath an award?+
How current is the spending data, and does it cover all fiscal years?+
list_agencies data reflects the current active fiscal year and quarter only. search_awards and search_subawards support time_period filters, so you can query historical fiscal years, but data freshness depends on how frequently USASpending.gov updates its records — typically within a few days of agency reporting deadlines.