USASpending.gov

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). fiscal_year defaults to the last completed fiscal year, not the current one (USAspending's own default, which right after October 1 holds o…

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…

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. Award-level outlays and total_account_obligation are partial or lagged File C measures, not a reliable amount paid; compare with total_obligatio…

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. File C can be partial or lagged; these rows do not establish the full award obligation or amount paid to the contractor. 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-endpo…

List program activity codes and names associated with a federal account. The source lists distinct programs across all reported fiscal years; it has no fiscal-year filter and includes no dollar amounts. fiscal_year is retained for compatibility, but does not filter this list. The response explicitly discloses any requested year that was not applied. Retrieves source pages internally, up to 2,000 records, and reports whether the list is complete. For single-year account resources and obligations, use get_federal_account_fy_snapshot with the numeric account_id returned by list_federal_accounts…

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, n…

List File C funding records associated with an IDV. Rows can identify the IDV itself as well as associated awards; they are not a complete list of child orders. File C coverage can be partial or lagged and does not establish the full child-order obligation or amount paid. Use get_idv_amounts() for reported child-order obligation totals and get_idv_activity() or get_idv_children() for child-order records.

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 subsidiar…

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). Parent (-P) totals include their children. Profiles use a separate recipient rollup and can differ from transaction searches by recipient_name and award-type scope.

Get the federal award totals for recipients located in a US state. Examples: '06' = California, '48' = Texas, '24' = Maryland, '51' = Virginia. Returns one summary: state name and code, total_prime_amount and total_prime_awards (all award types together), loan face value, award_amount_per_capita, total_outlays, and population / median household income (older Census vintages: see pop_year and mhi_year). It has no breakdown by agency, recipient or district; for those use spending_by_geography() or spending_by_category() with a time window. year: a fiscal year like 2026, 'all' (every year on fi…

List the reporting calendar and submission/certification deadlines. Returns available fiscal reporting periods and their scheduled start, due, certification and reveal dates. These are global calendar periods, not records of when individual agencies actually submitted or certified data. A listed period does not establish complete agency 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 controls the reported budgetary-resource values, not which account rows are included. When omitted, the source uses its latest available fiscal year, which may differ from the current fiscal year; check the returned fy value. 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 their exact PIID, across contracts AND IDVs. Looks for awards whose own PIID is exactly this value (the award_ids filter), in both contracts and IDVs, and says how many share it. match='exact' rows are the awards themselves: an IDV PIID returns the IDV (award_type='idv'; its Award Amount is what was obligated on the IDV record itself, usually 0, so use get_idv_amounts() for the order total). PIIDs are not unique: task and delivery order numbers like '0001' repeat under different parent IDVs, so check 'ambiguous' and tell matches apart by parent_idv_piid and Awarding Agency. …

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_…

Search USASpending recipients (vendors and grantees) by keyword. Returns paginated recipients with their UEI, DUNS, name, and a recipient 'id' hash for get_recipient_profile() and new_awards_over_time(). For get_recipient_children(), use the UEI (or legacy DUNS) from the parent (-P) row, not a recipient hash. 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).

Aggregate spending by a dimension (top vendors, top agencies, top NAICS, etc.). The 'category' parameter controls the grouping dimension. Common uses: - category='recipient': top vendors for a filter set (vendor landscape analysis) - category='awarding_subagency': which contracting offices within an agency - category='naics': which work categories got the most spending - category='psc': which product/service codes got the most spending - category='state_territory': geographic distribution - category='cfda': grant assistance listings Note: recipient category returns vendor names in ALL CAPS a…

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'. At least one filter is required. The API returns HTTP 500 on an empty filter set, so the requirement is enforced here with a clear error. program_numbers filters assistance awards by assistance listing (CFDA) number, e.g. ['93.778'] for Medicaid; use it with award_type='grants', 'loans', 'direct_payments', or 'other'. autocomplete_cfda() finds numbers by program name.

Find matching prime awards and their cumulative FFATA report totals. Filters select prime records, but subaward_count and subaward_obligation cover all reported subawards under each prime, not just subaward actions within time_period_start/end. This ranking is not a fiscal-period subaward ranking. For dated reports, pass a returned award_generated_internal_id to search_subawards(award_id=...), read every page, and retain action_date values inside the desired period. sort accepts: award_id, subaward_count, award_generated_internal_id, subaward_obligation. (These differ from search_subawards, …

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. recipient_uei is matched through the API's recipient text search (which covers name, UEI, and DUNS), so pass the plain 12-character UEI. Returns standard transaction fields: Action Date, Mod, Award ID, Action Type, Awarding Agency, Recipient Name. program_numbers filters assistance awards by assistance listing (C…

Aggregate spending amounts over time, grouped by fiscal year, quarter, or month. Use this to visualize spending trends, identify fiscal-year-end spikes, or compare spending patterns across years. Note: The API returns fiscal_year as a STRING. Cast to int for numeric comparisons. quarter and month are FISCAL periods (month 1 = October, quarter 1 = October-December). Buckets are clipped to the window, so a calendar-2025 window returns a partial fiscal_year '2025' (January- September only) and a partial '2026' (October-December); neither is that whole fiscal year. DoD contract actions are publ…