Search Federal Awards
usaspending_search_awardsRead-onlyIdempotent
Search federal awards by keyword, recipient, agency, award type, NAICS code, assistance listing (CFDA) number, PSC, DEF code, location, or date range. Returns ranked award summaries including recipient names, amounts, awarding agencies, and generated award IDs for use with usaspending_get_award; loan rows carry loan value, subsidy cost, and issue date in place of award amount and dates. Award types: A/B/C/D = contracts, IDV_A–IDV_E = IDVs, 02/03/04/05/F001/F002 = grants, 06/10/F006/F007 = direct payments, 07/08/F003/F004 = loans, 09/11/-1/F005/F008/F009/F010 = other assistance. Dates must be ISO 8601 (YYYY-MM-DD). Earliest data: 2007-10-01 via search API. DoD contracts have a 90-day publication lag.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "usaspending_search_awards"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit), but the keyset cursor below is only returned while the offset stays under 10,000 — capture the cursor pair before paging past that, or the only way forward is page numbers. | |
| sort | No | Sort field for results. Loans (07/08/F003/F004) sort by Loan Value, Subsidy Cost, Issued Date, Recipient Name, or Awarding Agency, defaulting to Loan Value. Every other group sorts by Award Amount, Total Outlays, Start Date, End Date, Recipient Name, or Awarding Agency, defaulting to Award Amount — except IDVs, which have no End Date. A sort the group does not support is rejected before the search runs. | |
| limit | No | Maximum results per page (1–100) | |
| order | No | Sort direction | desc |
| filters | No | Optional analytics-style filter object mirroring the shape the spending analytics tools accept, for reusing one filter set across tools. When both this object and the equivalent top-level flat filters are given, this object wins per-field. recipient_id is rejected — this endpoint silently ignores it; filter by recipient via recipient_name. | |
| keyword | No | Full-text search across award descriptions, recipient names, and place names; effective keywords need at least three characters without trimming; empty is unset | |
| def_codes | No | Filter by Disaster Emergency Fund Codes (DEF), e.g. ["Z"], or ["L", "M", "N", "O", "P"] for COVID-19: 1–3 letters or digits, sent uppercased — the codes usaspending_disaster_spending takes and usaspending_get_agency lists. Matches awards of any type funded under any of these codes. Amounts cover the whole matching award, not the share funded by the code, and DEF-filtered totals can be negative. An unknown code is rejected with the list of codes USAspending accepts. | |
| psc_codes | No | Filter by Product and Service Codes (PSC), e.g. ["Y1NE"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it ("Y1" covers "Y1NE"); several values match any of them. Only contracts and IDVs carry a PSC, so a call whose award types are all assistance types is rejected as psc_codes_type_mismatch, and pairing psc_codes with assistance_listings matches nothing, since no award carries both. Use usaspending_autocomplete_filters type=psc to look up codes. | |
| agency_name | No | Awarding top-tier or sub-tier agency name — use the matched name from usaspending_autocomplete_filters type=awarding_agency; use toptier_name to select the whole parent department. A sub-tier name shared by several parents matches under all parents. | |
| naics_codes | No | NAICS codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated. Use usaspending_autocomplete_filters type=naics to look up codes. | |
| time_period | No | Filter awards by date range (action date). Both blank means no date filter; one blank end is filled and named in the notice. | |
| recipient_name | No | Filter by recipient name (partial match); maps to this endpoint's recipient_search_text. This endpoint has no recipient_id filter — use usaspending_search_recipients to look up a recipient by name. | |
| location_filter | No | Filter by place of performance. Takes codes, not place names — use a geocoding server to resolve names to codes first. Blank fields are ignored, and an all-blank object is no location filter. The location sent is echoed as applied_location. | |
| award_type_codes | No | Filter by award type codes. All codes must belong to a single group: A/B/C/D (contracts), IDV_A/IDV_B/IDV_B_A/IDV_B_B/IDV_B_C/IDV_C/IDV_D/IDV_E (IDVs), 02/03/04/05/F001/F002 (grants), 06/10/F006/F007 (direct payments), 07/08/F003/F004 (loans), 09/11/-1/F005/F008/F009/F010 (other assistance). Defaults to contracts. Mixing groups causes a 422 error. The group decides which sort values apply. | |
| assistance_listings | No | Filter by Assistance Listing (CFDA) program numbers, e.g. ["15.507"]: two digits, a dot, then three digits or capital letters (11.67A). Matches an award when any of its listings equals one of these exactly; several values match any of them. A matching award's primary listing can differ from the one requested, and amounts cover the whole award, not that listing's share. Only assistance awards (grants, direct payments, loans, other assistance) carry listings, so a call whose award types are all contracts or IDVs — including a contract default — is rejected as assistance_listings_type_mismatch. Use usaspending_autocomplete_filters type=cfda to look up numbers. | |
| last_record_unique_id | No | Keyset-pagination cursor: the last_record_unique_id from a prior response page_metadata. Provide together with last_record_sort_value. | |
| last_record_sort_value | No | Keyset-pagination cursor: the last_record_sort_value from a prior response page_metadata. Provide together with last_record_unique_id to fetch the next page past the 50,000-result page-number cap. The upstream stops emitting the pair once page × limit reaches 10,000, so take it from a page below that offset. When both cursor fields are supplied, page is ignored. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | Per-page cap (limit) applied to this page, when truncated. | |
| page | No | Current page number returned | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of awards returned on this page, when truncated. | |
| notice | No | How to page on when more results may remain, which date bound was filled in when only the other was supplied, and the applied filters on an empty page. This endpoint supplies no total, so an empty page does not establish zero matches. Absent when none applies. | |
| results | No | Matching award summaries | |
| has_next | No | Whether more results may remain — set on a full page even when the upstream flag reports none. | |
| truncated | No | True when the upstream reports more results beyond this page (continue via page or the cursor). Absent on a full page the upstream marks as last, including every page past a 10,000-result offset where the upstream stops reporting continuation — has_next still says whether to request another. | |
| page_metadata | No | Pagination metadata. This endpoint does not return a total match count; use has_next and the cursor pair to page. | |
| applied_keyword | No | Keyword filter applied to this search | |
| applied_location | No | Place of performance location sent, as normalized (e.g. country=USA, state=NM, county=049) | |
| applied_def_codes | No | DEF codes sent, uppercased (comma-separated) | |
| applied_psc_codes | No | PSC codes sent, uppercased (comma-separated) | |
| upstream_messages | No | Notices the USAspending API returned with this response — e.g. a supplied filter it ignored because this endpoint does not support it. Every successful response also carries a standing advisory that search covers 2007-10-01 onward; that advisory is boilerplate, not a verdict on the dates requested. Present whenever the API returns any messages. | |
| applied_agency_name | No | Awarding agency name filter applied | |
| applied_naics_codes | No | NAICS codes filter applied (comma-separated) | |
| applied_time_period_end | No | End of the date range sent (YYYY-MM-DD), including a filled-in end | |
| applied_time_period_start | No | Start of the date range sent (YYYY-MM-DD), including a filled-in start | |
| applied_assistance_listings | No | Assistance Listing numbers filter applied (comma-separated) |