Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Look up valid code values for filter fields by searching free-text descriptions. Use the type parameter to select the lookup table: naics (NAICS industry codes), psc (product/service codes), cfda (CFDA/Assistance Listing program numbers), awarding_agency (agency and sub-agency names, each with its tier and top-tier parent — agency_name filters take the matched name; a sub-tier name shared by several parents matches under all parents), or recipient (recipient names with UEI/DUNS). Call this before filtering awards when you know a description but not the exact code. Returns matching codes and names for use in other tool filters.
Lookup table to search: naics (industry codes), psc (product/service codes, for the psc_codes filter), cfda (Assistance Listing program numbers, for the assistance_listings filter), awarding_agency (agency and sub-agency names), recipient (recipient names). Both filters are taken by usaspending_search_awards and by the filters object of usaspending_spending_by_category, usaspending_spending_by_geography, and usaspending_spending_over_time.
Free-text search string — use a description, keyword, or partial code to find matches
Maximum number of results to return (1–500), enforced client-side. Agency matches combine independently capped top-tier then sub-tier buckets, preserving their order without deduplicating names; offices are excluded. The recipient lookup unions three upstream match buckets (name, UEI, DUNS) and can return up to 3x this value, so its results are capped to this limit before returning — the cap keeps them in bucket order, so name matches fill the page first and identifier matches appear only in whatever room is left. To resolve a specific UEI or DUNS, pass the identifier itself as search_text. Every lookup returns at most limit rows.
Tool list last changed Oct 25, 2026.
Look up valid code values for filter fields by searching free-text descriptions. Use the type parameter to select the lookup table: naics (NAICS industry codes), psc (product/service codes), cfda (CFDA/Assistance Listing program numbers), awarding_agency (agency and sub-agency names, each with its tier and top-tier parent — agency_name filters take the matched name; a sub-tier name shared by several parents matches under all parents), or recipient (recipient names with UEI/DUNS). Call this before filtering awards when you know a description but not the exact code. Returns matching codes and names for use in other tool filters.
| Argument | Type | Description |
|---|---|---|
| type* | string | Lookup table to search: naics (industry codes), psc (product/service codes, for the psc_codes filter), cfda (Assistance Listing program numbers, for the assistance_listings filter), awarding_agency (agency and sub-agency names), recipient (recipient names). Both filters are taken by usaspending_search_awards and by the filters object of usaspending_spending_by_category, usaspending_spending_by_geography, and usaspending_spending_over_time. |
| limit | integer | Maximum number of results to return (1–500), enforced client-side. Agency matches combine independently capped top-tier then sub-tier buckets, preserving their order without deduplicating names; offices are excluded. The recipient lookup unions three upstream match buckets (name, UEI, DUNS) and can return up to 3x this value, so its results are capped to this limit before returning — the cap keeps them in bucket order, so name matches fill the page first and identifier matches appear only in whatever room is left. To resolve a specific UEI or DUNS, pass the identifier itself as search_text. Every lookup returns at most limit rows. |
| search_text* | string | Free-text search string — use a description, keyword, or partial code to find matches |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"type",
"search_text"
],
"properties": {
"type": {
"enum": [
"naics",
"psc",
"cfda",
"awarding_agency",
"recipient"
],
"type": "string",
"description": "Lookup table to search: naics (industry codes), psc (product/service codes, for the psc_codes filter), cfda (Assistance Listing program numbers, for the assistance_listings filter), awarding_agency (agency and sub-agency names), recipient (recipient names). Both filters are taken by usaspending_search_awards and by the filters object of usaspending_spending_by_category, usaspending_spending_by_geography, and usaspending_spending_over_time."
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 500,
"minimum": 1,
"description": "Maximum number of results to return (1–500), enforced client-side. Agency matches combine independently capped top-tier then sub-tier buckets, preserving their order without deduplicating names; offices are excluded. The recipient lookup unions three upstream match buckets (name, UEI, DUNS) and can return up to 3x this value, so its results are capped to this limit before returning — the cap keeps them in bucket order, so name matches fill the page first and identifier matches appear only in whatever room is left. To resolve a specific UEI or DUNS, pass the identifier itself as search_text. Every lookup returns at most limit rows."
},
"search_text": {
"type": "string",
"minLength": 1,
"description": "Free-text search string — use a description, keyword, or partial code to find matches"
}
},
"additionalProperties": false
}Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, infrastructure law, etc.) broken down by agency, CFDA assistance program, recipient, or geography. Use the dimension parameter to select the breakdown axis: overview (top-level totals), agency, cfda, recipient, or geography. Filter by DEF codes (Disaster/Emergency Funding codes) to isolate a specific emergency appropriation. DEF codes appear in usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| limit | integer | Maximum results per page (1–100). Applies to the agency, cfda, recipient, and geography dimensions; geography pages through its areas ranked by aggregated_amount, highest first. Ignored for overview. |
| filters | object | Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography) |
| dimension* | string | Breakdown axis: overview (top-level totals and DEF code funding), agency (by awarding agency), cfda (by assistance program), recipient (by recipient), geography (by state/county) |
| spending_type | string | Data type for the agency dimension: award (award-level obligations and outlays) or total (includes direct non-award spending, plus total budgetary resources). Ignored for cfda, recipient, and overview, which report award-level amounts either way; the geography dimension is not user-controllable and always reports obligation-based amounts. |
Fetch an agency's fiscal-year overview including mission, budgetary resources, obligation and outlay totals (for the most recent fiscal year with reported budget data), sub-agency count, and DEF codes for disaster/emergency funding. Also returns a paginated sub-agency breakdown with obligation and transaction counts for the same fiscal year as the budget totals (the current fiscal year when no budget year is available within 5 seconds); sub_agency_fiscal_year names the year it covers. Accepts exactly one of a 3-digit toptier_code (e.g., 097 for DoD, 012 for Agriculture) or an agency_slug (e.g., department-of-defense) — both appear in usaspending_list_agencies results and award search results. When the budget or sub-agency request fails, the overview is still returned and unavailable_sections names each missing section with its reason.
| Argument | Type | Description |
|---|---|---|
| page | integer | Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list. |
| agency_slug | string | URL-friendly agency slug (e.g., department-of-defense) — from usaspending_list_agencies or award search results. Use either toptier_code or agency_slug, not both. |
| toptier_code | string | 3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list."
},
"agency_slug": {
"type": "string",
"description": "URL-friendly agency slug (e.g., department-of-defense) — from usaspending_list_agencies or award search results. Use either toptier_code or agency_slug, not both."
},
"toptier_code": {
"type": "string",
"description": "3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both."
}
},
"additionalProperties": false
}Fetch full details of a federal award by its generated unique award ID. Returns contract or assistance award data including recipient identity (UEI, parent organization, business categories), agency hierarchy, period of performance, place of performance, Assistance Listings with the obligation under each, loan face value and subsidy cost for loans, funding account linkages (account_obligations_by_defc), parent IDV information, and subaward count. Use generated_internal_id values from usaspending_search_awards as input. Recipient and parent recipient hashes can be passed to usaspending_get_recipient; NAICS codes can be used in usaspending_search_awards filters, and Assistance Listing numbers in its assistance_listings filter. For IDV-category awards (category="idv"), use usaspending_get_idv_awards to list the child contracts and task/delivery orders placed under them.
| Argument | Type | Description |
|---|---|---|
| award_id* | string | Generated unique award ID (e.g., CONT_AWD_FA862118F6251_9700_FA862115D6276_9700) — use generated_internal_id from usaspending_search_awards |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"award_id"
],
"properties": {
"award_id": {
"type": "string",
"minLength": 1,
"description": "Generated unique award ID (e.g., CONT_AWD_FA862118F6251_9700_FA862115D6276_9700) — use generated_internal_id from usaspending_search_awards"
}
},
"additionalProperties": false
}List the Treasury federal accounts that funded an award, with the amount obligated from each and the funding agency behind it. This is the award → appropriation link: each row returns federal_account (AGENCY-MAIN format, e.g. 080-0120) to chain into usaspending_get_federal_account for the account budget detail. The award_id must be a generated_unique_award_id — from usaspending_search_awards (generated_internal_id field) or usaspending_get_award. Distinct from usaspending_get_award account_obligations_by_defc, which breaks funding down by Disaster/Emergency Funding code rather than by account. An award_id that does not exist returns an empty list rather than an error.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| limit | integer | Maximum results per page (1–100) |
| award_id* | string | Award generated_unique_award_id (e.g., CONT_AWD_GSFC0198106DNAS526555_8000_-NONE-_-NONE-) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"award_id"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based)"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum results per page (1–100)"
},
"award_id": {
"type": "string",
"minLength": 1,
"description": "Award generated_unique_award_id (e.g., CONT_AWD_GSFC0198106DNAS526555_8000_-NONE-_-NONE-) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award"
}
},
"additionalProperties": false
}List subaward contracts or grants under a prime federal award. Reveals the sub-contractor or sub-grantee layer — the organizations that actually perform the work. Each row shows the subaward number, amount, description, action date, and recipient. Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| sort | string | Sort field for subawards |
| limit | integer | Maximum subawards per page (1–100) |
| order | string | Sort direction |
| award_id* | string | Generated unique award ID (generated_internal_id from usaspending_search_awards) |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"award_id"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based)"
},
"sort": {
"enum": [
"subaward_number",
"description",
"action_date",
"amount",
"recipient_name"
],
"type": "string",
"default": "action_date",
"description": "Sort field for subawards"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum subawards per page (1–100)"
},
"order": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Sort direction"
},
"award_id": {
"type": "string",
"minLength": 1,
"description": "Generated unique award ID (generated_internal_id from usaspending_search_awards)"
}
},
"additionalProperties": false
}List individual transactions (contract modifications, grant amendments) on a federal award. Each transaction represents a change event — obligation modifications, performance period extensions, scope changes, etc. Use this to trace the spending history and obligation changes over the life of an award. Award IDs come from usaspending_search_awards (generated_internal_id field).
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| sort | string | Sort field for transactions |
| limit | integer | Maximum transactions per page (1–100) |
| order | string | Sort direction |
| award_id* | string | Generated unique award ID (generated_internal_id from usaspending_search_awards) |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"award_id"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based)"
},
"sort": {
"enum": [
"action_date",
"federal_action_obligation",
"modification_number"
],
"type": "string",
"default": "action_date",
"description": "Sort field for transactions"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum transactions per page (1–100)"
},
"order": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Sort direction"
},
"award_id": {
"type": "string",
"minLength": 1,
"description": "Generated unique award ID (generated_internal_id from usaspending_search_awards)"
}
},
"additionalProperties": false
}Fetch a federal account's budget data: total obligations, gross outlays, and budgetary resources, plus the per-Treasury-Account-Symbol (TAS) component breakdown in children. fiscal_year selects a reporting year; omit it for the current federal fiscal year. An empty year retains metadata and a notice, without substituting another year. Federal accounts connect appropriations law to actual agency spending. Account codes come from usaspending_search_federal_accounts (its account_number output field) or usaspending_get_award_federal_accounts (its federal_account field), and are formatted as AGENCY-MAIN (e.g., 097-0100 for DoD Operation and Maintenance). For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown.
| Argument | Type | Description |
|---|---|---|
| fiscal_year | any | Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default. |
| account_code* | string | Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"account_code"
],
"properties": {
"fiscal_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 2001,
"description": "Integer federal fiscal year from 2001 through the current federal fiscal year"
},
{
"type": "string",
"maxLength": 0,
"minLength": 0,
"description": "Blank form value; leaves the fiscal year unset"
}
],
"description": "Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default."
},
"account_code": {
"type": "string",
"minLength": 1,
"description": "Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts."
}
},
"additionalProperties": false
}Fetch a federal account's obligations broken down by program activity (what the money funds) or object class (what it buys — personnel, supplies, contracts). Use the dimension parameter to select the axis. fiscal_year scopes financial reporting periods to the full October–September year, not award action dates; omit it for all available periods. Account codes are AGENCY-MAIN format and come from usaspending_search_federal_accounts (its account_number output field), usaspending_get_award_federal_accounts (its federal_account field), or usaspending_get_federal_account. Paginated with an honest total count. For the account's own metadata and top-level totals, use usaspending_get_federal_account.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| limit | integer | Maximum results per page (1–100) |
| dimension* | string | Breakdown axis: program_activity (obligations by the program the funds support) or object_class (obligations by the category of goods/services purchased) |
| fiscal_year | any | Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default. |
| account_code* | string | Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts. |
List child contracts and task/delivery orders placed under an IDV (Indefinite Delivery Vehicle) award. Each row includes the generated_unique_award_id to chain into usaspending_get_award for full detail. The award_id must be the generated_unique_award_id of the parent IDV — obtainable from usaspending_search_awards (generated_internal_id field) or from usaspending_get_award. IDV category awards returned by usaspending_get_award have child orders accessible via this tool.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| sort | string | Field to sort child awards by (e.g., obligated_amount, period_of_performance_start_date) |
| type | string | Type of child awards to list: child_awards = task/delivery orders, child_idvs = sub-IDVs, grandchild_awards = orders under sub-IDVs |
| limit | integer | Maximum results per page (1–100) |
| order | string | Sort direction |
| award_id* | string | Parent IDV generated_unique_award_id (e.g., CONT_IDV_NNK14MA74C_8000) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award |
Fetch a recipient's full profile including address, business type codes, parent organization, alternate names, and total transaction and loan amounts. Recipient IDs are UUID hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_search_recipients or usaspending_get_award. Totals cover the trailing 12 months unless fiscal_year selects one fiscal year, and period names the window. For a recipient's totals by award type, use usaspending_spending_over_time with filters.recipient_id and award_type_codes. UEI and DUNS values can be used to cross-reference with SAM.gov and SEC EDGAR.
| Argument | Type | Description |
|---|---|---|
| fiscal_year | integer | Fiscal year to scope the totals to (e.g., 2024, which runs October 2023 through September 2024). Omit for the trailing 12 months. |
| recipient_id* | string | Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"recipient_id"
],
"properties": {
"fiscal_year": {
"type": "integer",
"maximum": 2030,
"minimum": 2001,
"description": "Fiscal year to scope the totals to (e.g., 2024, which runs October 2023 through September 2024). Omit for the trailing 12 months."
},
"recipient_id": {
"type": "string",
"minLength": 1,
"description": "Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award"
}
},
"additionalProperties": false
}List top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the latest reported period. Returns the full directory unless limit is supplied; optional pagination slices the provider-sorted directory. Use this as the entry point for agency navigation — toptier codes and agency slugs are required inputs for usaspending_get_agency and agency-based filters on spending analysis tools.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number when limit is supplied (defaults to page 1); ignored without limit. |
| sort | string | Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amount |
| limit | integer | Agencies per page; omitted returns the full directory. No maximum. |
| order | string | Sort direction: asc or desc |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number when limit is supplied (defaults to page 1); ignored without limit."
},
"sort": {
"enum": [
"agency_name",
"budget_authority_amount",
"obligated_amount",
"outlay_amount"
],
"type": "string",
"default": "agency_name",
"description": "Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amount"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Agencies per page; omitted returns the full directory. No maximum."
},
"order": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "asc",
"description": "Sort direction: asc or desc"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| page | integer | 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 | string | 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 | integer | Maximum results per page (1–100) |
| order | string | Sort direction |
List and keyword-search federal accounts by agency identifier or title keyword. Returns account numbers, names, managing agencies, and budgetary resources. fiscal_year selects the resource amounts, not account membership; omit it for the latest available submission year. Search and detail totals use different calculations and can differ for the same year. Use account_number from results as input to usaspending_get_federal_account for full budget detail. Use usaspending_list_agencies to look up agency_identifier codes (3-digit strings, e.g. "097" for DoD).
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| limit | integer | Maximum results per page (1–100) |
| keyword | string | Filter accounts by name or title keyword (e.g., "defense", "transportation") |
| sort_field | string | Field to sort results by |
| fiscal_year | any | Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default. |
| sort_direction | string | Sort direction |
| agency_identifier | string |
Search for organizations or individuals receiving federal funds by name, UEI (Unique Entity Identifier), or DUNS. Returns recipient hash IDs, UEI/DUNS identifiers, total award amounts, and hierarchy level. Results are paginated — use page to retrieve matches beyond the first page; page_metadata.total reports the full match count. Recipient hash IDs from this tool can be passed to usaspending_get_recipient for full profiles. Recipient level: P = parent organization, C = child entity, R = standalone.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) — request the next page to retrieve matches beyond the first |
| limit | integer | Maximum results per page (1–100) |
| keyword* | string | Name, UEI, DUNS, or keyword to search for — partial matches are supported. Surrounding whitespace is trimmed; blank text applies no keyword filter and is disclosed. |
| award_type | string | Filter by award type category to scope the total amounts returned |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"keyword"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based) — request the next page to retrieve matches beyond the first"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum results per page (1–100)"
},
"keyword": {
"type": "string",
"minLength": 1,
"description": "Name, UEI, DUNS, or keyword to search for — partial matches are supported. Surrounding whitespace is trimmed; blank text applies no keyword filter and is disclosed."
},
"award_type": {
"enum": [
"contracts",
"grants",
"direct_payments",
"loans",
"other_financial_assistance"
],
"type": "string",
"description": "Filter by award type category to scope the total amounts returned"
}
},
"additionalProperties": false
}Aggregate federal spending grouped by a specific dimension: NAICS industry code, PSC product/service code, awarding agency, funding agency, CFDA assistance program, or recipient. Returns top items with obligation amounts — useful for trend and breakdown analysis. Filter by keyword, award type, agency, recipient, NAICS code, Assistance Listing, PSC, DEF code, or date range. Chain NAICS, PSC, and CFDA codes back into these filters, into usaspending_search_awards filters, or into usaspending_autocomplete_filters lookups. recipient_duns rows carry recipient_id, which opens the recipient profile in usaspending_get_recipient, and uei.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| limit | integer | Maximum items to return (1–100) |
| filters | object | Optional filters to scope the aggregation |
| category* | string | Breakdown dimension: naics (industry), psc (product/service code), awarding_agency, awarding_subagency, funding_agency, funding_subagency, cfda (assistance programs), or recipient_duns (recipients) |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"category"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based)"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum items to return (1–100)"
},
"filters": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Full-text keyword filters"
},
"def_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,3}$",
"description": "Disaster Emergency Fund Code, e.g. Z or L"
},
"description": "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": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,4}$",
"description": "Product and Service Code or prefix, e.g. Y1NE or Y1"
},
"description": "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": {
"type": "string",
"description": "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": {
"type": "array",
"items": {
"type": "string"
},
"description": "NAICS code filters"
},
"recipient_id": {
"type": "string",
"description": "Exact recipient hash ID filter"
},
"time_period_end": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "End date (YYYY-MM-DD). Given alone, the window starts at 2007-10-01, the earliest searchable date."
},
"award_type_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Award type code filters (A/B/C/D, 02–05, etc.)"
},
"time_period_start": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "Start date (YYYY-MM-DD), 2007-10-01 or later. Given alone, the window runs through today (UTC)."
},
"assistance_listings": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
"description": "Assistance Listing number, e.g. 15.507"
},
"description": "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."
}
},
"description": "Optional filters to scope the aggregation",
"additionalProperties": false
},
"category": {
"enum": [
"naics",
"psc",
"awarding_agency",
"awarding_subagency",
"funding_agency",
"funding_subagency",
"cfda",
"recipient_duns"
],
"type": "string",
"description": "Breakdown dimension: naics (industry), psc (product/service code), awarding_agency, awarding_subagency, funding_agency, funding_subagency, cfda (assistance programs), or recipient_duns (recipients)"
}
},
"additionalProperties": false
}Aggregate federal spending by state, county, or congressional district. Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns. Filter by keyword, award type, agency, recipient, NAICS code, Assistance Listing, PSC, DEF code, or date range. Areas are ranked by obligation and capped at limit; to retrieve specific areas, including ones ranked past the cap, list their codes in shape_codes — a 2-letter postal code for state, a 5-digit state + county FIPS code for county, or a 4-digit state FIPS + district number for district — NOT place names. Resolve place names to these codes using a geocoding server (Census or OpenStreetMap) first. Chain per-capita results with Census population data for meaningful comparisons.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum geographic areas to return, ranked by aggregated_amount descending (1–500). The upstream endpoint is not paginated — it returns every matching area in one response — so this caps client-side. A nationwide county query matches over 3,000 areas; use shape_codes to retrieve one ranked past the cap. |
| scope* | string | Which location to aggregate by: place_of_performance (where work is done) or recipient_location (where the recipient is based) |
| filters | object | Optional filters to scope the spending aggregation |
| geo_layer* | string | Geographic granularity: state (states, DC, and territories), county (county-level), or district (congressional district) |
Fetch aggregated federal obligation amounts grouped by fiscal year, fiscal quarter, or fiscal month. All grouping is relative to the US government fiscal year (Oct–Sep), so fiscal month 1 is October, not January. Filter by award type, agency, recipient, keyword, NAICS code, Assistance Listing, PSC, or DEF code to trace spending trends in a specific area; award types default to contracts. Returns per-period totals and optional breakdowns by award category (contracts, grants, direct payments, IDVs, loans, other).
| Argument | Type | Description |
|---|---|---|
| group* | string | Time grouping: fiscal_year (annual US govt FY: Oct–Sep), quarter (fiscal quarter), or month (fiscal month — an ordinal within the fiscal year, where 1 = October) |
| filters | object | Filters to scope the time-series aggregation. Defaults to contract awards when omitted. |
| subawards | boolean | Aggregate subaward data instead of prime award data |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"group"
],
"properties": {
"group": {
"enum": [
"fiscal_year",
"quarter",
"month"
],
"type": "string",
"description": "Time grouping: fiscal_year (annual US govt FY: Oct–Sep), quarter (fiscal quarter), or month (fiscal month — an ordinal within the fiscal year, where 1 = October)"
},
"filters": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Full-text keyword filters"
},
"def_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,3}$",
"description": "Disaster Emergency Fund Code, e.g. Z or L"
},
"description": "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": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,4}$",
"description": "Product and Service Code or prefix, e.g. Y1NE or Y1"
},
"description": "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": {
"type": "string",
"description": "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": {
"type": "array",
"items": {
"type": "string"
},
"description": "NAICS code filters"
},
"recipient_id": {
"type": "string",
"description": "Exact recipient hash ID filter"
},
"time_period_end": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "End of the time window (YYYY-MM-DD). Given alone, the window starts at 2007-10-01, the earliest searchable date."
},
"award_type_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Award type code filters (A/B/C/D, 02–05, etc.); groups may be mixed. When omitted, defaults to contracts (A, B, C, D)."
},
"time_period_start": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "Start of the time window (YYYY-MM-DD), 2007-10-01 or later. Given alone, the window runs through today (UTC)."
},
"assistance_listings": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
"description": "Assistance Listing number, e.g. 15.507"
},
"description": "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."
}
},
"description": "Filters to scope the time-series aggregation. Defaults to contract awards when omitted.",
"additionalProperties": false
},
"subawards": {
"type": "boolean",
"default": false,
"description": "Aggregate subaward data instead of prime award data"
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"dimension"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based)"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum results per page (1–100). Applies to the agency, cfda, recipient, and geography dimensions; geography pages through its areas ranked by aggregated_amount, highest first. Ignored for overview."
},
"filters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Recipient search text, trimmed before sending. Omitted or blank means no query filter. Ignored with a notice on other dimensions."
},
"def_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Optional for overview totals and funding; required for agency, cfda, recipient, and geography breakdowns. DEF codes appear in usaspending_get_agency def_codes fields."
},
"geo_layer": {
"enum": [
"state",
"county"
],
"type": "string",
"description": "Geographic layer for geography dimension (state or county)"
},
"award_type_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Award type code filters"
}
},
"description": "Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography)",
"additionalProperties": false
},
"dimension": {
"enum": [
"overview",
"agency",
"cfda",
"recipient",
"geography"
],
"type": "string",
"description": "Breakdown axis: overview (top-level totals and DEF code funding), agency (by awarding agency), cfda (by assistance program), recipient (by recipient), geography (by state/county)"
},
"spending_type": {
"enum": [
"award",
"total"
],
"type": "string",
"default": "award",
"description": "Data type for the agency dimension: award (award-level obligations and outlays) or total (includes direct non-award spending, plus total budgetary resources). Ignored for cfda, recipient, and overview, which report award-level amounts either way; the geography dimension is not user-controllable and always reports obligation-based amounts."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"account_code",
"dimension"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based)"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum results per page (1–100)"
},
"dimension": {
"enum": [
"program_activity",
"object_class"
],
"type": "string",
"description": "Breakdown axis: program_activity (obligations by the program the funds support) or object_class (obligations by the category of goods/services purchased)"
},
"fiscal_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 2001,
"description": "Integer federal fiscal year from 2001 through the current federal fiscal year"
},
{
"type": "string",
"maxLength": 0,
"minLength": 0,
"description": "Blank form value; leaves the fiscal year unset"
}
],
"description": "Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default."
},
"account_code": {
"type": "string",
"minLength": 1,
"description": "Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"award_id"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based)"
},
"sort": {
"type": "string",
"default": "obligated_amount",
"description": "Field to sort child awards by (e.g., obligated_amount, period_of_performance_start_date)"
},
"type": {
"enum": [
"child_awards",
"child_idvs",
"grandchild_awards"
],
"type": "string",
"default": "child_awards",
"description": "Type of child awards to list: child_awards = task/delivery orders, child_idvs = sub-IDVs, grandchild_awards = orders under sub-IDVs"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum results per page (1–100)"
},
"order": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Sort direction"
},
"award_id": {
"type": "string",
"minLength": 1,
"description": "Parent IDV generated_unique_award_id (e.g., CONT_IDV_NNK14MA74C_8000) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award"
}
},
"additionalProperties": false
}| filters |
| object |
| 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 | string | Full-text search across award descriptions, recipient names, and place names |
| def_codes | array | 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 | array | 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 | string | 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 | array | Filter by NAICS industry codes (e.g., ["541512"]). Use usaspending_autocomplete_filters type=naics to look up codes. |
| time_period | object | 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 | string | 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 | object | 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 | array | 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 | array | 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 | integer | 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 | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "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": {
"enum": [
"Award Amount",
"Total Outlays",
"Start Date",
"End Date",
"Loan Value",
"Subsidy Cost",
"Issued Date",
"Recipient Name",
"Awarding Agency"
],
"type": "string",
"description": "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": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum results per page (1–100)"
},
"order": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Sort direction"
},
"filters": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Full-text search terms across award descriptions, recipient names, and places"
},
"def_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,3}$",
"description": "Disaster Emergency Fund Code, e.g. Z or L"
},
"description": "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": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,4}$",
"description": "Product and Service Code or prefix, e.g. Y1NE or Y1"
},
"description": "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": {
"type": "string",
"description": "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": {
"type": "array",
"items": {
"type": "string"
},
"description": "NAICS industry codes to require, e.g., [\"541512\"]"
},
"recipient_name": {
"type": "string",
"description": "Recipient name search (partial match); maps to recipient_search_text. Use instead of recipient_id, which this endpoint ignores."
},
"time_period_end": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "End date (YYYY-MM-DD). Given alone, the range starts at 2007-10-01, the earliest searchable date."
},
"award_type_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Award type codes; all must belong to one group (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). When non-empty, overrides the top-level award_type_codes and decides which sort values apply; an empty array falls back to the top-level value."
},
"time_period_start": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "Start date (YYYY-MM-DD); earliest valid 2007-10-01. Given alone, the range runs through today (UTC)."
},
"assistance_listings": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
"description": "Assistance Listing number, e.g. 15.507"
},
"description": "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."
}
},
"description": "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.",
"additionalProperties": false
},
"keyword": {
"type": "string",
"description": "Full-text search across award descriptions, recipient names, and place names"
},
"def_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,3}$",
"description": "Disaster Emergency Fund Code, e.g. Z or L"
},
"description": "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": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,4}$",
"description": "Product and Service Code or prefix, e.g. Y1NE or Y1"
},
"description": "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": {
"type": "string",
"description": "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": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete_filters type=naics to look up codes."
},
"time_period": {
"type": "object",
"required": [
"start_date",
"end_date"
],
"properties": {
"end_date": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "End date in ISO 8601 format (YYYY-MM-DD). Blank (\"\") leaves the end open, filled with today (UTC)."
},
"start_date": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "Start date in ISO 8601 format (YYYY-MM-DD); earliest valid: 2007-10-01. Blank (\"\") leaves the start open, filled with 2007-10-01."
}
},
"description": "Filter awards by date range (action date). Both blank means no date filter; one blank end is filled and named in the notice.",
"additionalProperties": false
},
"recipient_name": {
"type": "string",
"description": "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": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name"
},
"state": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^(?:[A-Za-z]{2}|\\d{2})$"
}
],
"description": "Under USA (the default): a US state, DC, territory, freely associated state, or armed-forces code as a 2-letter postal code (NM, PR, FM, AE) or 2-digit FIPS code (35). Under another country: that country's own 2-letter subdivision code (ON with CAN)."
},
"county": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^(?:\\d{3}|\\d{5})$"
}
],
"description": "US county FIPS code: 3 digits with state (049 with state NM), or the 5-digit state + county code (35049, Santa Fe County, NM), whose first two digits set the state — the form usaspending_spending_by_geography county rows carry as shape_code."
},
"country": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^[A-Za-z]{3}$"
}
],
"description": "ISO 3166-1 alpha-3 country code (e.g., USA); USA when omitted. A US territory code — PRI, GUM, VIR, ASM, MNP — is sent as USA with the territory as state."
}
},
"description": "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.",
"additionalProperties": false
},
"award_type_codes": {
"type": "array",
"items": {
"type": "string"
},
"default": [
"A",
"B",
"C",
"D"
],
"minItems": 1,
"description": "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": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
"description": "Assistance Listing number, e.g. 15.507"
},
"description": "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": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "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": {
"type": "string",
"description": "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."
}
},
"additionalProperties": false
}| 3-digit agency identifier code (e.g., "097" for Department of Defense). Use usaspending_list_agencies to look up codes. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number (1-based)"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum results per page (1–100)"
},
"keyword": {
"type": "string",
"description": "Filter accounts by name or title keyword (e.g., \"defense\", \"transportation\")"
},
"sort_field": {
"enum": [
"account_name",
"account_number",
"budgetary_resources",
"managing_agency"
],
"type": "string",
"default": "budgetary_resources",
"description": "Field to sort results by"
},
"fiscal_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 2001,
"description": "Integer federal fiscal year from 2001 through the current federal fiscal year"
},
{
"type": "string",
"maxLength": 0,
"minLength": 0,
"description": "Blank form value; leaves the fiscal year unset"
}
],
"description": "Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default."
},
"sort_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Sort direction"
},
"agency_identifier": {
"type": "string",
"description": "3-digit agency identifier code (e.g., \"097\" for Department of Defense). Use usaspending_list_agencies to look up codes."
}
},
"additionalProperties": false
}| subawards |
| boolean |
| Include subaward data instead of prime award data |
| shape_codes | array | Return only these areas (1–500 codes), in the shape_code form this tool returns for geo_layer: 2-letter postal code for state ("NY"), 5-digit state + county FIPS for county ("36117" is Wayne County, NY), or 4-digit state FIPS + 2-digit district number for district ("3623" is NY-23, "5600" is Wyoming's at-large seat). Selection runs over every area the filters matched, so it reaches areas ranked past limit; selected areas stay ranked by aggregated_amount and capped at limit. A code that matches no area is named in the notice. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"scope",
"geo_layer"
],
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 500,
"minimum": 1,
"description": "Maximum geographic areas to return, ranked by aggregated_amount descending (1–500). The upstream endpoint is not paginated — it returns every matching area in one response — so this caps client-side. A nationwide county query matches over 3,000 areas; use shape_codes to retrieve one ranked past the cap."
},
"scope": {
"enum": [
"place_of_performance",
"recipient_location"
],
"type": "string",
"description": "Which location to aggregate by: place_of_performance (where work is done) or recipient_location (where the recipient is based)"
},
"filters": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Full-text keyword filter (e.g., [\"cybersecurity\", \"cloud\"])"
},
"def_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,3}$",
"description": "Disaster Emergency Fund Code, e.g. Z or L"
},
"description": "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": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Za-z]{1,4}$",
"description": "Product and Service Code or prefix, e.g. Y1NE or Y1"
},
"description": "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": {
"type": "string",
"description": "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": {
"type": "array",
"items": {
"type": "string"
},
"description": "NAICS industry codes to include"
},
"recipient_id": {
"type": "string",
"description": "Exact recipient hash ID to filter awards"
},
"time_period_end": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "End of time period (YYYY-MM-DD). Given alone, the period starts at 2007-10-01, the earliest searchable date."
},
"award_type_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Award type codes: A/B/C/D (contracts), IDV_A–IDV_E (IDVs), 02–05 (grants), 06/10 (direct payments), 07/08 (loans), 09/11 (insurance and other assistance), -1 (unspecified). Groups may be mixed here. Omit to aggregate every type."
},
"time_period_start": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"description": "Date as YYYY-MM-DD; month and day may be unpadded"
}
],
"description": "Start of time period (YYYY-MM-DD), 2007-10-01 or later. Given alone, the period runs through today (UTC)."
},
"assistance_listings": {
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
"description": "Assistance Listing number, e.g. 15.507"
},
"description": "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."
}
},
"description": "Optional filters to scope the spending aggregation",
"additionalProperties": false
},
"geo_layer": {
"enum": [
"state",
"county",
"district"
],
"type": "string",
"description": "Geographic granularity: state (states, DC, and territories), county (county-level), or district (congressional district)"
},
"subawards": {
"type": "boolean",
"default": false,
"description": "Include subaward data instead of prime award data"
},
"shape_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(?:[A-Za-z]{2}|\\d{4,5})$",
"description": "One area code: 2-letter postal code (e.g. \"NY\"), 5-digit county FIPS (e.g. \"36117\"), or 4-digit district code (e.g. \"3623\")"
},
"maxItems": 500,
"minItems": 1,
"description": "Return only these areas (1–500 codes), in the shape_code form this tool returns for geo_layer: 2-letter postal code for state (\"NY\"), 5-digit state + county FIPS for county (\"36117\" is Wayne County, NY), or 4-digit state FIPS + 2-digit district number for district (\"3623\" is NY-23, \"5600\" is Wyoming's at-large seat). Selection runs over every area the filters matched, so it reaches areas ranked past limit; selected areas stay ranked by aggregated_amount and capped at limit. A code that matches no area is named in the notice."
}
},
"additionalProperties": false
}