get_award_funding
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_idv_children
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').
lookup_piid
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.
autocomplete_psc
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.
autocomplete_naics
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.
list_toptier_agencies
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().
get_agency_overview
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().
get_agency_awards
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_naics_details
Get details for a NAICS code (2-6 digits).
Returns the NAICS description, parent categories, and child subcategories
if applicable.
get_psc_filter_tree
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_state_profile
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.
search_subawards
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).
spending_by_subaward_grouped
Search subawards using the standard filters object (grouped result set).
Unlike search_subawards which is scoped to a single prime, this returns
subawards grouped under their primes given a filter set similar to
search_awards. Useful for FFATA-wide analysis ("show me all DoD
subcontracts on cyber awards in FY2026").
search_recipients
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`.
get_recipient_profile
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() or autocomplete_recipient().
year: optional 'all' or a fiscal year like '2026'. Default is 'latest'.
get_recipient_children
Get the child recipients (subsidiaries) of a parent recipient hash.
Pass a recipient hash with -P (parent) suffix to retrieve subsidiary
recipients. The endpoint returns a list of -C suffixed hashes representing
children. For -R (regular, no parent) recipients this returns an empty
list or 4xx.
Useful for mapping corporate structures (e.g. Lockheed Martin -P -> all
its subsidiaries -C).
autocomplete_recipient
Find recipient hashes by partial name or UEI/DUNS.
Returns matching recipients with their hash IDs and metadata. Use the hash
from results in get_recipient_profile() or get_recipient_children().
list_states
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.
get_agency_budgetary_resources
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.
get_agency_sub_agencies
List the subordinate (subtier) organizations of a toptier agency.
Returns each sub-agency with its obligations, outlays, 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.
get_agency_federal_accounts
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.
get_agency_object_classes
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_agency_program_activities
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.
get_agency_obligations_by_award_category
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_award_funding_rollup
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.
get_award_subaward_count
Count of subawards (FFATA subcontracts/subawards) reported on an award.
get_award_federal_account_count
Count of distinct federal accounts (TAS) funding an award.
get_award_transaction_count
Count of transactions (modifications) on an award.
awards_last_updated
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).
spending_by_transaction
Search at the transaction (modification) level.
Unlike search_awards which returns one row per award, this returns one
row per transaction (initial action plus every modification). Useful for
tracking obligation events over time, ceiling adjustments, deobligations,
and admin mods.
Returns standard transaction fields: Action Date, Mod, Award ID,
Action Type, Awarding Agency, Recipient Name.
spending_by_geography
Geographic breakdown of spending.
scope: 'recipient_location' (where the recipient is) or 'place_of_performance'
(where the work happens).
geo_layer: 'state', 'county', or 'district'.
new_awards_over_time
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 will reject calls without recipient_id with HTTP 422.
get_idv_amounts
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.
get_idv_funding
List the funding records (File C) for an IDV's child orders.
get_idv_funding_rollup
Funding rollup totals for an IDV (single dict, not paginated).
get_idv_activity
List child task/delivery orders awarded under an IDV.
autocomplete_awarding_agency
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.
autocomplete_funding_agency
Find funding agency names by partial match (companion to awarding agency).
autocomplete_cfda
Find CFDA (Catalog of Federal Domestic Assistance) program numbers
by partial title or program number. CFDA codes are used in grants.
autocomplete_glossary
Find glossary terms (acquisition + spending vocabulary) by partial match.
get_award_types_reference
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.
get_def_codes_reference
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_glossary
Get the full USASpending glossary of acquisition + spending terms.
get_submission_periods
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.
list_federal_accounts
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'}.
get_federal_account_detail
Get an individual federal account's metadata + budgetary resources.
get_federal_account_object_classes
Get the object class breakdown of obligations for a federal account.
Note: this endpoint requires POST (not GET like the other federal account
sub-endpoints). Live audit caught this; the body is empty.
get_federal_account_program_activities
Get the program activities funded under a federal account.
get_federal_account_fy_snapshot
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.