USASpending APIusaspending.gov ↗
Access US federal spending data: search contracts and grants, get award details, list agencies by budget authority, and group spending by recipient or agency.
What is the USASpending API?
This API exposes 5 endpoints covering US federal government spending data from USASpending.gov, including award search, detailed contract records, and agency budget figures. The search_awards endpoint accepts complex filter objects — keywords, time periods, award type codes, and agency filters — returning paginated award results with recipient names and obligated amounts. Two additional search endpoints let you group spending by category or look up recipient organizations by name.
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.
from parse_apis.usaspending_gov_data_api import USASpending, SpendingCategory, AgencySortField, Sort
client = USASpending()
# List top agencies sorted by budget authority in descending order
for agency in client.toptieragencies.list(sort=AgencySortField.BUDGET_AUTHORITY_AMOUNT, order=Sort.DESC):
print(agency.agency_name, agency.budget_authority_amount, agency.abbreviation)
# Search for government contract awards related to Salesforce
for award in client.awardsummaries.search(keywords="Salesforce"):
print(award.award_id, award.recipient_name, award.award_amount)
# Navigate to full details for this award
detail = award.details()
print(detail.total_obligation, detail.category, detail.type_description)
print(detail.recipient.recipient_name, detail.recipient.recipient_uei)
print(detail.period_of_performance.start_date, detail.period_of_performance.end_date)
break
# Search spending grouped by funding agency
for item in client.spendingbycategories.search(category=SpendingCategory.FUNDING_AGENCY):
print(item.name, item.amount, item.code)
# Find recipients matching a name
for match in client.recipientmatches.search(search_text="Microsoft"):
print(match.recipient_name, match.uei)
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 Details
The search_awards endpoint accepts a filters object that can include keywords, time_period, award_type_codes, and agency parameters, returning an array of award objects with fields like Award ID, Recipient Name, Award Amount, and generated_internal_id. Pagination is handled through page_metadata, which exposes hasNext, last_record_unique_id, and last_record_sort_value for cursor-style traversal. Once you have a generated_internal_id, pass it to get_award_details to retrieve the full record: recipient (including business categories and location), funding_agency, awarding_agency, total_obligation, period_of_performance dates, and a plain-text description of the award.
Agency and Spending Category Data
The list_agencies endpoint returns all federal toptier agencies with their budget_authority_amount and percentage_of_total_budget_authority, sortable by field and order. The search_spending_by_category endpoint groups spending totals by a chosen category — accepted values include awarding_agency, awarding_subagency, funding_agency, recipient, and state_territory — with each result carrying a name, id, code, and amount. A default time_period filter is applied automatically when none is provided in the filters object.
Recipient Lookup
The search_recipients endpoint performs a name-based autocomplete search, returning matching organizations with recipient_name, recipient_level, uei (Unique Entity Identifier), and duns. This is useful for resolving exact recipient identifiers before running a filtered search_awards query tied to a specific vendor or contractor.
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?+
- Track all federal contracts awarded to a specific company by filtering
search_awardswith a keyword or recipient name. - Compare agency budget authority amounts using
list_agenciessorted bybudget_authority_amountdescending. - Map federal spending by state using
search_spending_by_categorywithcategoryset tostate_territory. - Audit a specific contract's period of performance, awarding agency, and total obligation via
get_award_details. - Resolve a vendor's UEI or DUNS number before querying awards using
search_recipients. - Identify which agencies are spending most on a specific keyword by combining
search_awardsfilters withsearch_spending_by_category. - Build a spending dashboard showing top recipients by obligated amount using the
recipientcategory insearch_spending_by_category.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does USASpending.gov have an official developer API?+
How does pagination work in `search_awards`?+
page_metadata object in each response includes hasNext (boolean), last_record_unique_id, and last_record_sort_value. Use these values to request the next page of results in subsequent calls.What filters can I pass to `search_awards`?+
filters object supports keywords, time_period, award_type_codes, and agency parameters. You can also pass a keywords string directly as a top-level input for simpler keyword-only queries.Does the API return sub-award or transaction-level data?+
Are all award types returned by `search_awards` by default?+
award_type_codes is omitted from the filters object, the endpoint returns results across award types. Pass specific codes in that field to restrict results to contracts, grants, loans, or other award categories.