USASpending.gov

Find awarding agency names by partial match. USASpending search filters require the EXACT awarding agency name (slugs return zero). Use this to resolve a partial name to the canonical one before passing to search_awards() awarding_agency parameter.

Find CFDA (Catalog of Federal Domestic Assistance) program numbers by partial title or program number. CFDA codes are used in grants.

Find funding agency names by partial match (companion to awarding agency).

Find glossary terms (acquisition + spending vocabulary) by partial match.

Autocomplete lookup for NAICS codes. Accepts partial codes ('541') or keywords ('software'). Returns matching NAICS entries with code and description. Minimum 2 characters required. Short queries silently match substrings inside parenthetical notes (e.g. 'x' matches 'except') and produce nonsense results, so we require 2+ chars. exclude_retired defaults to True. The upstream NAICS taxonomy still returns codes retired in 2012/2017/2022; these are almost never what callers want. Set exclude_retired=False to include them.

Autocomplete lookup for Product/Service Codes (PSC). Works best with code prefixes ('R499', 'D3', 'AJ') or keywords ('professional', 'application'). Returns matching PSC entries with code and description. Minimum 2 characters required. Single-character queries return first-N alphabetical results from the upstream API (useless for matching) and empty strings return HTTP 400.

Find recipient names by partial name or UEI/DUNS. NOTE: this endpoint returns recipient NAMES only. It does NOT return the recipient hash needed by get_recipient_profile() and get_recipient_children() (and its uei/duns fields come back null). To get a hash, take a name from here and pass it to search_recipients(), whose results carry the hash in their 'id' field.

Get the timestamp of the last USASpending award data refresh. Use this to determine data freshness when comparing to other sources (SAM.gov Contract Awards API for example).

Get award summary totals for an agency in a given fiscal year. Returns obligation totals by award category. toptier_code is auto-padded to 3 digits if a shorter numeric value is supplied.

Get an agency's budgetary resources by fiscal year. Returns total budgetary resources, obligations, outlays, and discretionary vs mandatory breakdown for each fiscal year on file.

List the Treasury Account Symbols (federal accounts) used by an agency. Returns each federal account with its obligated amount and gross outlay for the given fiscal year. Useful for understanding how an agency's money flows through Treasury.

List the object class breakdown (what an agency spends money on). Object classes are OMB categories: Personnel Compensation, Travel, Contractual Services, Equipment, Grants, etc. Useful for understanding what types of expenditures an agency makes.

Get an agency's obligation breakdown by award category. Returns total obligated dollars split by category: contracts, IDVs, grants, loans, direct payments, other. Quick way to see what mix of award types an agency uses (heavy contractor agency vs grant-issuing agency vs mixed).

Get summary information for a specific agency in a given fiscal year. toptier_code is the 3- or 4-digit agency code (e.g. '097' for DoD, '075' for HHS, '080' for NASA). Shorter inputs like '97' are left-padded to '097' automatically. Get valid codes via list_toptier_agencies().

List the program activities (specific programs) within an agency. Program activities are the specific named programs that obligate funds (e.g., 'Cybersecurity and Infrastructure Security Agency'). Useful for pinpointing which program funds a specific activity.

List the subordinate (subtier) organizations of a toptier agency. Returns each sub-agency with its obligations, transaction count, and new-award count for the given fiscal year. Useful for finding the canonical subtier name to pass into search_awards() awarding_subagency. sort accepts name, total_obligations, transaction_count, or new_award_count (this endpoint has no outlay column; a former 'total_outlays' option was rejected by the API with HTTP 400).

Count awards matching filters, broken down by award category. Returns counts grouped by: contracts, idvs, grants, loans, direct_payments, other. Use this for dimensional analysis: how many FFP vs T&M awards, how many competed vs sole-source, how many small business set-asides, etc. Unlike search_awards, this returns total counts across ALL award categories in a single call (not just the one specified in award_type). The award_type parameter is ignored here; filters apply to the count query directly. def_codes filters to Disaster Emergency Fund codes; see get_def_codes_reference(). At least one filter is required (the API rejects empty filter sets with HTTP 400). Typical usage: pass time_period_start + time_period_end, or a keywords/agency filter.

Fetch full details for a single award by its generated_internal_id. Use the generated_internal_id value returned by search_awards to fetch the complete award record. Returns: PIID, full description, total obligation, recipient details, parent award info, latest transaction contract data (competition, set-aside, pricing type), period of performance, place of performance, NAICS hierarchy, PSC hierarchy, base and all options value, and sub-award totals. Accepts either a generated award id (CONT_AWD_*, CONT_IDV_*, ASST_NON_*, ASST_AGG_*) or the numeric internal database id from a prior response. Example generated_award_id format: CONT_AWD_N0002424C0085_9700_N0002421D0001_9700

Count of distinct federal accounts (TAS) funding an award.

Fetch File C funding data for an award: federal account, object class, program activity. Shows which Treasury accounts, object classes, and program activities funded an award. Useful for appropriations analysis and understanding what colors of money paid for what. Sort fields: reporting_fiscal_date, account_title, transaction_obligated_amount, object_class.

Get a rollup of an award's funding totals. Returns total transaction obligated amount, awarding agency count, funding agency count, and federal account count for a single award. Useful for a one-line summary of an award's funding picture.

Count of subawards (FFATA subcontracts/subawards) reported on an award.

Count of transactions (modifications) on an award.

Return the full mapping of award type codes to descriptions. Returns the canonical reference: contracts (A=BPA Call, B=Purchase Order, C=Delivery Order, D=Definitive Contract), IDVs, grants, loans, etc. Authoritative source if you're unsure what a code letter means.

Return all Disaster Emergency Fund (DEFC) codes with public laws. DEFCs are used to filter awards funded by specific supplemental appropriations (COVID-19, IIJA, IRA, etc.).

Get an individual federal account's metadata + budgetary resources.

Get a single-fiscal-year snapshot of a federal account's resources. Important: this endpoint takes the numeric `account_id` (e.g. 4595), NOT the alphanumeric `account_number` (e.g. "027-5183") used by the other federal-account endpoints. The list_federal_accounts response includes both fields per record. Pass the integer account_id here.

Get the object class breakdown of obligations for a federal account. IMPORTANT: the returned obligations are CUMULATIVE across all reported fiscal years (FY2017 onward, the DATA Act window), not a single year. They are NOT comparable to get_federal_account_fy_snapshot(), which is single-year (verified live: account 021-0725 summed to $3.38B here vs $0.42B obligated in its FY2024 snapshot). The upstream endpoint has no year control: a fiscal_year body parameter is accepted but ignored, so none is exposed here. Note: this endpoint requires POST (not GET like the other federal account sub-endpoints). Live audit caught this; the body is empty.

Get the program activities funded under a federal account.

Get the full USASpending glossary of acquisition + spending terms.

List child task/delivery orders awarded under an IDV. Results are ALWAYS sorted by obligated amount, descending; the endpoint accepts no sort or order parameters. (Earlier releases exposed sort/order here, but the API silently ignored them: the advertised default of period_of_performance_start_date was never the actual ordering. Round 10 audit finding.) For date-ordered children use get_idv_children(), whose endpoint does honor sort/order. hide_edge_cases=True filters out child awards missing obligated/awarded amounts or end dates.

Top-line amounts for an Indefinite Delivery Vehicle (IDV). Returns child IDV count, child award count, child award total obligation, and base/option values rolled up across all task/delivery orders under the IDV. Pass a CONT_IDV_* generated_internal_id.

Fetch child awards (task/delivery orders) under an IDV. For a Multiple Award IDV, child_awards returns the task orders or delivery orders placed against it. For a parent IDV, child_idvs returns the downstream IDV structure. grandchild_awards walks the hierarchy. Field name differences from search_awards: children use 'piid' (not 'Award ID'), 'obligated_amount' (not 'Award Amount'), and 'generated_unique_award_id' (not 'generated_internal_id'). An active vehicle can legitimately return zero children here: USASpending's award cross-linking has gaps. Treat an empty result as a reporting gap, not proof that no orders exist. A search_awards call with keywords=['<IDV PIID>'] sometimes recovers the orders, but it can also be empty on the same vehicle.

List the funding records (File C) for an IDV's child orders.

Funding rollup totals for an IDV (single dict, not paginated).

Get details for a NAICS code (2-6 digits). Returns the NAICS description, parent categories, and child subcategories if applicable.

Get the PSC hierarchy tree. Pass an empty path for the top-level. Drill down with paths like 'Service/R/' to get the service professional services tree, or 'Product/5' for product codes starting with 5.

Get the child recipients (subsidiaries) of a parent recipient. Pass the parent recipient's 12-character UEI (or legacy 9-digit DUNS). Do NOT pass a recipient hash: the /recipient/children/ endpoint is the one recipient endpoint keyed by UEI/DUNS, and it rejects hashes with HTTP 400. Get the UEI from search_recipients() results (the 'uei' field of the -P row) or from get_recipient_profile(). Returns the child recipients, each with its own -C suffixed recipient_id hash usable with get_recipient_profile(). Useful for mapping corporate structures (e.g. Lockheed Martin parent -> all its subsidiaries). year: optional 'all', 'latest', or a fiscal year like 2026. The upstream endpoint returns a JSON array; it is wrapped here as {"results": [...], "total": N} to keep the dict-only response invariant.

Get full profile for a recipient by their USASpending hash. Returns recipient details: name, UEI, DUNS, business categories, location, parent (if any), and lifetime award totals. The hash is the 'id' field returned by search_recipients(). (autocomplete_recipient does NOT return hashes; it is a name lookup only.) year: optional 'all' or a fiscal year like 2026 (int or str both accepted). Default is 'latest' (trailing 12 months).

Get spending profile for a US state by its 2-digit FIPS code. Examples: '06' = California, '48' = Texas, '24' = Maryland, '51' = Virginia. Returns award totals, top agencies, top recipients, and district data.

Return the list of agency submission periods (when each agency last submitted data for each fiscal period). Useful for understanding which quarters of which fiscal years have full data coverage.

Fetch the full transaction (modification) history for an award. Every modification, option exercise, and de-obligation is a transaction. Modification number '0' is the original base award. Use to understand the full lifecycle of a contract including its descriptive text at each point in time. Returns per transaction: id, type, action_date, action_type, modification_number, description, federal_action_obligation.

List Treasury federal accounts (TAS) with budgetary resources. keyword filters by account name or AID. fiscal_year defaults to current FY. sort is a dict like {'field':'budgetary_resources','direction':'desc'}.

List all states with their FIPS codes and award totals. Returns the full list of US states/territories with FIPS codes you can pass to get_state_profile(). The /recipient/state/ endpoint returns a JSON array (not an object). We wrap it in {"results": [...]} to keep the tool return type consistent with every other endpoint in this MCP.

List all top-tier federal agencies tracked by USASpending. Returns agency codes, names, abbreviations, and current-year budgetary resources. Use the returned 'toptier_code' values with get_agency_overview().

Look up awards by PIID or PIID prefix with automatic award-type detection. Convenience tool: tries contracts first, then IDVs if no match. Uses keyword search under the hood, which behaves as a substring match on the PIID field, so you can pass a full PIID or a contracting-office prefix (e.g. 'N00024' for NAVSEA, 'W91CRB' for Army Contracting Command, 'FA8650' for AFRL). Returns the matching awards with basic fields. Use get_award_detail() with the returned generated_internal_id for the full record. Handy for enriching PRISM, Contract Court, or FPDS exports where you have a PIID but don't know whether it's a contract or IDV.

Pipeline trend of new awards to a recipient over time. REQUIRES recipient_id (the recipient hash with -P suffix for parent-level rollup, or -R for a single recipient). Returns counts of new awards grouped by month, quarter, or fiscal year. The endpoint rejects calls without recipient_id with HTTP 422, and it also requires a time_period. When you omit the dates, a default range covering all searchable data (2007-10-01 through 2099-09-30) is sent automatically.

Search federal awards (contracts, IDVs, grants, loans, etc.) on USASpending.gov. This is the primary workhorse for finding awards. Returns matching awards with standard fields (Award ID, Recipient, Description, Amount, Agencies, NAICS, PSC, dates). Use get_award_detail() with the generated_internal_id from results to get full award details. Important rules: - award_type groups cannot be mixed; pick one category per call - time_period_start/end use YYYY-MM-DD format - award_amount_min/max are in USD - place_of_performance_state is a 2-letter USPS code (e.g. 'MD', 'VA') - For loans, use award_type='loans' and sort='Loan Value' - def_codes filters to Disaster Emergency Fund codes (COVID-19, IIJA, IRA supplementals); see get_def_codes_reference() for the list Filtering to specific contracting commands (NAVSEA, AFRL, etc.): USASpending's subtier level is at the service branch (Department of the Navy, Army, Air Force), not the contracting command. To filter to a specific command, use keywords with the PIID office prefix instead: - NAVSEA contracts: keywords=['N00024'] - Army Contracting: keywords=['W91CRB'] - AFRL: keywords=['FA8650'] - NAVAIR: keywords=['N00019'] This performs a substring match on the PIID field and is more reliable than the award_ids filter for partial matches. Common filter value references: - set_aside_type_codes: SBA, SBP, 8A, 8AN, HZC, HZS, SDVOSBS, SDVOSBC, WOSB, WOSBSS, EDWOSB, EDWOSBSS, VSA - extent_competed_type_codes: A (Full & Open), B, C, D, E, F, G, CDO, NDO - contract_pricing_type_codes: J (FFP), Y (T&M), Z (LH), U (CPFF), V (CPIF), R (CPAF), L (FP Incentive), M (FP Award Fee) IMPORTANT: awarding_agency/funding_agency must be the FULL TOPTIER NAME, not a slug. Use 'Department of Defense', NOT 'department-of-defense'. Slugs silently return zero results, and so does any name that is not a toptier agency: the military departments are SUBTIERS, so pass awarding_agency='Department of Defense' with awarding_s…

Search USASpending recipients (vendors and grantees) by keyword. Returns paginated recipients with their UEI, DUNS, name, and a recipient 'id' that downstream tools use as the hash for get_recipient_profile and get_recipient_children. keyword can match recipient name, UEI, or DUNS. If omitted, returns the top recipients ranked by `sort`.

Search FFATA subaward reports on USASpending. Returns the FFATA subaward records (subcontracts under prime contracts and subawards under prime grants). Complementary to the SAM.gov FFATA endpoints but expressed at the USASpending data model. award_id: optional generated_internal_id (CONT_AWD_..., ASST_NON_..., etc.) to scope subawards to a single prime award. If omitted, returns subawards across all primes for the page. Pagination uses page (1-indexed) and limit (1-100).