usaspending-mcp-server
An open-source MCP server that provides 18 tools to access and analyze US federal spending data from USAspending.gov. It allows agents to list agencies, search awards by various criteria, retrieve detailed award records including transactions and subawards, look up recipient and agency profiles, and aggregate spending by geography, category, or time period.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://usaspending.caseyjhand.com/mcpWhat its tools do
18 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Read-only (18)
usaspending_list_agenciesusaspending_autocomplete_filtersusaspending_search_awardsusaspending_get_awardusaspending_get_award_transactionsusaspending_get_award_subawardsusaspending_get_award_federal_accountsusaspending_get_idv_awardsusaspending_search_recipientsusaspending_get_recipientusaspending_get_agencyusaspending_spending_by_geographyusaspending_spending_by_categoryusaspending_spending_over_timeusaspending_disaster_spendingusaspending_get_federal_accountusaspending_get_federal_account_breakdownusaspending_search_federal_accounts
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Search federal awards by keyword, recipient, or agency
- List top-tier federal agencies with budget totals
- Aggregate spending by geography or category
- Retrieve detailed award records and transactions
Source and maintenance
Community listingRegistry 0.7.1
- Maintenance checked
Protocol and capabilities
- Server
- usaspending-mcp-server 0.7.1
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 18 advertised
- Resources
- 1 advertised
- Resource templates
- 1 advertised
- Prompts
- 0 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
18 advertised
usaspending_list_agencies — List Federal Agencies
Advertised read-only
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.
usaspending_list_agencies input schema
{
"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
}usaspending_list_agencies output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"total",
"agency_count",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"total": {
"type": "number",
"description": "Total number of agencies in the full directory before pagination"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"agency_name",
"toptier_code"
],
"properties": {
"agency_name": {
"type": "string",
"description": "Full agency name"
},
"agency_slug": {
"type": "string",
"description": "URL-friendly agency slug (e.g., department-of-defense) — accepted by usaspending_get_agency"
},
"fiscal_year": {
"type": "number",
"description": "Provider reporting fiscal year for the latest reported period"
},
"abbreviation": {
"type": "string",
"description": "Agency abbreviation or acronym"
},
"toptier_code": {
"type": "string",
"description": "Directory toptier agency code (e.g., 097 for DoD, 1601 for Labor); three or four digits — accepted by usaspending_get_agency and search_federal_accounts agency_identifier"
},
"outlay_amount": {
"type": "number",
"description": "Total outlay amount in USD for the latest reported period"
},
"fiscal_quarter": {
"type": "number",
"description": "Provider reporting fiscal quarter for the latest reported period"
},
"obligated_amount": {
"type": "number",
"description": "Total obligated amount in USD for the latest reported period"
},
"budget_authority_amount": {
"type": "number",
"description": "Total budget authority amount in USD for the latest reported period"
}
},
"description": "Agency entry with codes, slugs, and fiscal year budget data",
"additionalProperties": false
},
"description": "List of top-tier federal agencies with budget and obligation data"
},
"has_next": {
"type": "boolean",
"description": "Whether another page exists; present only when limit is supplied"
},
"totalCount": {
"type": "number",
"description": "Total number of agencies in the full directory before pagination"
},
"agency_count": {
"type": "number",
"description": "Total number of top-tier federal agencies returned"
}
},
"additionalProperties": false
}usaspending_list_agencies annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_autocomplete_filters — Autocomplete Codes and Names
Advertised read-onlyOpen-world
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.
usaspending_autocomplete_filters input schema
{
"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
}usaspending_autocomplete_filters output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"type",
"search_text",
"results",
"total",
"lookup_type",
"query",
"result_count"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit that was applied, when truncated."
},
"type": {
"type": "string",
"description": "Lookup table searched"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"no_match",
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `no_match`: No codes or names matched the search text. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"query": {
"type": "string",
"description": "Search text sent to the autocomplete API"
},
"shown": {
"type": "number",
"description": "Number of results returned, when truncated."
},
"total": {
"type": "number",
"description": "Number of results returned"
},
"notice": {
"type": "string",
"description": "How to reach the matches left out when truncated, or — when limit is 500 and all 500 slots filled — that the upstream maximum was reached and more matches may exist. Absent otherwise."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uei": {
"type": "string",
"description": "Unique Entity Identifier (SAM.gov) — recipient type only; populated when the search text matches a UEI"
},
"code": {
"type": "string",
"description": "Code value (NAICS code, PSC code, or Assistance Listing/CFDA number); use this in filter parameters — an Assistance Listing number goes in usaspending_search_awards assistance_listings. Agency rows carry toptier_code instead."
},
"duns": {
"type": "string",
"description": "DUNS number (legacy) — recipient type only; populated when the search text matches a DUNS"
},
"name": {
"type": "string",
"description": "Human-readable name or description; for awarding_agency, the matched agency's own name, which for a sub-agency differs from toptier_name"
},
"tier": {
"enum": [
"toptier",
"subtier"
],
"type": "string",
"description": "awarding_agency only: toptier for a department-level agency, subtier for a component under one"
},
"abbreviation": {
"type": "string",
"description": "awarding_agency only: the matched agency's own abbreviation, when it has one"
},
"subtier_code": {
"type": "string",
"description": "awarding_agency only: the matched sub-tier agency code, when supplied"
},
"toptier_code": {
"type": "string",
"description": "awarding_agency only: the 3-digit top-tier agency code, accepted by usaspending_get_agency"
},
"toptier_name": {
"type": "string",
"description": "awarding_agency only: the top-tier parent name. Use the matched name in agency_name on usaspending_search_awards and spending analytics to select the sub-agency; use toptier_name intentionally to select its whole parent department."
}
},
"description": "Matched entry — code/name for code lookups, name with tier and top-tier parent for agencies, name plus optional UEI/DUNS for recipients",
"additionalProperties": false
},
"description": "Matching codes and names"
},
"truncated": {
"type": "boolean",
"description": "True when more matches exist beyond the limit and were left out. Absent when every match was returned."
},
"lookup_type": {
"type": "string",
"description": "Lookup table that was searched"
},
"search_text": {
"type": "string",
"description": "Search text used"
},
"result_count": {
"type": "number",
"description": "Number of matching results returned"
}
},
"additionalProperties": false
}usaspending_autocomplete_filters annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}usaspending_search_awards — Search Federal Awards
Advertised read-onlyOpen-world
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.
usaspending_search_awards input schema
{
"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; effective terms need at least three characters without trimming; nonempty nested values override flat values"
},
"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: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize; unclassified spellings remain provider-validated; nonempty nested values override flat values"
},
"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; effective keywords need at least three characters without trimming; empty is unset"
},
"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 codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated. Use usaspending_autocomplete_filters type=naics to look up codes."
},
"time_period": {
"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
}usaspending_search_awards output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"page_metadata",
"page",
"has_next"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "Per-page cap (limit) applied to this page, when truncated."
},
"page": {
"type": "number",
"description": "Current page number returned"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_keyword",
"invalid_naics_code",
"incomplete_cursor",
"api_unavailable",
"api_timeout",
"pagination_limit_exceeded",
"date_before_earliest",
"date_range_inverted",
"unsupported_sort",
"assistance_listings_type_mismatch",
"psc_codes_type_mismatch",
"invalid_location"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_keyword`: An effective keyword has fewer than three characters. `invalid_naics_code`: An effective NAICS code is known to be invalid. `incomplete_cursor`: Only one of last_record_sort_value and last_record_unique_id was supplied. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. `pagination_limit_exceeded`: page multiplied by limit exceeds the endpoint 50,000-result page window and no cursor was supplied. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. `date_range_inverted`: Both ends of the date range were supplied and the start date falls after the end date. `unsupported_sort`: The sort value is not one the award type group supports. `assistance_listings_type_mismatch`: assistance_listings was given while the award type codes include contract or IDV codes, or were left at the contract default. `psc_codes_type_mismatch`: psc_codes was given while the award type codes include assistance codes. `invalid_location`: location_filter names an unknown US state, a county without a state or under an armed-forces code, a county or FIPS-number state under a non-USA country, or parts that place it in different states. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of awards returned on this page, when truncated."
},
"notice": {
"type": "string",
"description": "How to page on when more results may remain, which date bound was filled in when only the other was supplied, and the applied filters on an empty page. This endpoint supplies no total, so an empty page does not establish zero matches. Absent when none applies."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"award_id": {
"type": "string",
"description": "Display award ID (piid, fain, or uri) — NOT the chaining ID"
},
"end_date": {
"type": "string",
"description": "Award end date (YYYY-MM-DD)"
},
"award_type": {
"type": "string",
"description": "Award type description"
},
"loan_value": {
"type": "number",
"description": "Face value of the loan in USD (loans only — they carry no award_amount)"
},
"start_date": {
"type": "string",
"description": "Award start date (YYYY-MM-DD)"
},
"agency_slug": {
"type": "string",
"description": "URL-friendly awarding-agency slug (e.g., national-aeronautics-and-space-administration) — pass to usaspending_get_agency as agency_slug. Absent when the agency has no profile page."
},
"description": {
"type": "string",
"description": "Award description"
},
"issued_date": {
"type": "string",
"description": "Date the loan was issued (YYYY-MM-DD; loans only — they carry no start or end date)"
},
"award_amount": {
"type": "number",
"description": "Total award amount in USD"
},
"subsidy_cost": {
"type": "number",
"description": "Original subsidy cost of the loan in USD — the estimated long-term cost to the government (loans only)"
},
"total_outlays": {
"type": "number",
"description": "Total outlays in USD"
},
"funding_agency": {
"type": "string",
"description": "Name of the funding agency"
},
"recipient_name": {
"type": "string",
"description": "Name of the award recipient"
},
"awarding_agency": {
"type": "string",
"description": "Name of the awarding agency"
},
"awarding_sub_agency": {
"type": "string",
"description": "Name of the awarding sub-agency"
},
"place_of_performance": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City of performance"
},
"state": {
"type": "string",
"description": "State code of performance"
},
"country": {
"type": "string",
"description": "Country code of performance"
}
},
"description": "Place of performance location",
"additionalProperties": false
},
"generated_internal_id": {
"type": "string",
"description": "Generated unique award ID — pass to usaspending_get_award to fetch full details"
}
},
"description": "Award summary with amounts, agencies, and chaining IDs",
"additionalProperties": false
},
"description": "Matching award summaries"
},
"has_next": {
"type": "boolean",
"description": "Whether more results may remain — set on a full page even when the upstream flag reports none."
},
"truncated": {
"type": "boolean",
"description": "True when the upstream reports more results beyond this page (continue via page or the cursor). Absent on a full page the upstream marks as last, including every page past a 10,000-result offset where the upstream stops reporting continuation — has_next still says whether to request another."
},
"page_metadata": {
"type": "object",
"required": [
"has_next",
"page",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page number"
},
"limit": {
"type": "number",
"description": "Results per page"
},
"has_next": {
"type": "boolean",
"description": "Whether more results may remain — true on a full page even when the upstream flag reports none, since this endpoint under-reports continuation on a final full page and on every page past a 10,000-result offset. A short or empty page marks the end."
},
"last_record_unique_id": {
"type": "number",
"description": "Keyset-pagination cursor for the next page — pass back as last_record_unique_id alongside last_record_sort_value. Absent on the same pages that omit last_record_sort_value."
},
"last_record_sort_value": {
"type": "string",
"description": "Keyset-pagination cursor for the next page — pass back as last_record_sort_value to continue past the 50,000-result page limit. Absent once page × limit reaches 10,000, where the upstream stops emitting the pair."
}
},
"description": "Pagination metadata. This endpoint does not return a total match count; use has_next and the cursor pair to page.",
"additionalProperties": false
},
"applied_keyword": {
"type": "string",
"description": "Keyword filter applied to this search"
},
"applied_location": {
"type": "string",
"description": "Place of performance location sent, as normalized (e.g. country=USA, state=NM, county=049)"
},
"applied_def_codes": {
"type": "string",
"description": "DEF codes sent, uppercased (comma-separated)"
},
"applied_psc_codes": {
"type": "string",
"description": "PSC codes sent, uppercased (comma-separated)"
},
"upstream_messages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notices the USAspending API returned with this response — e.g. a supplied filter it ignored because this endpoint does not support it. Every successful response also carries a standing advisory that search covers 2007-10-01 onward; that advisory is boilerplate, not a verdict on the dates requested. Present whenever the API returns any messages."
},
"applied_agency_name": {
"type": "string",
"description": "Awarding agency name filter applied"
},
"applied_naics_codes": {
"type": "string",
"description": "NAICS codes filter applied (comma-separated)"
},
"applied_time_period_end": {
"type": "string",
"description": "End of the date range sent (YYYY-MM-DD), including a filled-in end"
},
"applied_time_period_start": {
"type": "string",
"description": "Start of the date range sent (YYYY-MM-DD), including a filled-in start"
},
"applied_assistance_listings": {
"type": "string",
"description": "Assistance Listing numbers filter applied (comma-separated)"
}
},
"additionalProperties": false
}usaspending_search_awards annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}usaspending_get_award — Get Award Details
Advertised read-only
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.
usaspending_get_award input schema
{
"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
}usaspending_get_award output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"fain": {
"type": "string",
"description": "Federal Award Identification Number (for assistance)"
},
"piid": {
"type": "string",
"description": "Procurement Instrument Identifier (for contracts)"
},
"type": {
"type": "string",
"description": "Award type code"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"award_not_found",
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `award_not_found`: No award exists for the given award ID. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"naics": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "NAICS industry code"
},
"description": {
"type": "string",
"description": "NAICS industry description"
}
},
"description": "NAICS code (contracts)",
"additionalProperties": false
},
"category": {
"type": "string",
"description": "Award category: contract, idv, grant, loans, direct payment, insurance, or other"
},
"recipient": {
"type": "object",
"properties": {
"uei": {
"type": "string",
"description": "Recipient Unique Entity Identifier"
},
"location": {
"type": "object",
"properties": {
"zip5": {
"type": "string",
"description": "Recipient ZIP code, preserving leading zeros"
},
"city_name": {
"type": "string",
"description": "Recipient city"
},
"state_code": {
"type": "string",
"description": "Recipient state code"
},
"county_name": {
"type": "string",
"description": "Recipient county"
},
"country_code": {
"type": "string",
"description": "Recipient three-letter country code (e.g. USA)"
},
"congressional_code": {
"type": "string",
"description": "Recipient congressional district, preserving leading zeros"
}
},
"description": "Recipient address; absent when upstream reports no location fields",
"additionalProperties": false
},
"parent_uei": {
"type": "string",
"description": "Parent organization Unique Entity Identifier"
},
"recipient_id": {
"type": "string",
"description": "Recipient hash ID — pass to usaspending_get_recipient for full profile"
},
"recipient_name": {
"type": "string",
"description": "Recipient legal business name"
},
"business_categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Recipient business category names (e.g. \"Higher Education\", \"U.S. Local Government\") — not the codes usaspending_get_recipient returns as business_types"
},
"parent_recipient_id": {
"type": "string",
"description": "Parent recipient hash ID (ends in -P) — pass to usaspending_get_recipient for the parent organization profile"
},
"parent_recipient_name": {
"type": "string",
"description": "Parent organization name"
}
},
"description": "Recipient details",
"additionalProperties": false
},
"date_signed": {
"type": "string",
"description": "Date award was signed (YYYY-MM-DD)"
},
"description": {
"type": "string",
"description": "Award description"
},
"parent_award": {
"type": "object",
"properties": {
"award_id": {
"type": "string",
"description": "Parent award display ID"
},
"agency_name": {
"type": "string",
"description": "Parent award agency name"
},
"type_description": {
"type": "string",
"description": "Parent award type description"
},
"generated_unique_award_id": {
"type": "string",
"description": "Parent award chaining ID — pass to usaspending_get_award for parent IDV details"
}
},
"description": "Parent IDV information (contracts only)",
"additionalProperties": false
},
"total_outlays": {
"type": "number",
"description": "Total outlay amount in USD"
},
"funding_agency": {
"type": "object",
"properties": {
"subtier_name": {
"type": "string",
"description": "Sub-tier funding agency name"
},
"toptier_code": {
"type": "string",
"description": "Top-tier funding agency code"
},
"toptier_name": {
"type": "string",
"description": "Top-tier funding agency name"
}
},
"description": "Funding agency hierarchy",
"additionalProperties": false
},
"subaward_count": {
"type": "number",
"description": "Number of subawards; use with usaspending_get_award_subawards"
},
"awarding_agency": {
"type": "object",
"properties": {
"subtier_name": {
"type": "string",
"description": "Sub-tier agency name"
},
"toptier_code": {
"type": "string",
"description": "Top-tier agency code"
},
"toptier_name": {
"type": "string",
"description": "Top-tier agency name"
},
"toptier_slug": {
"type": "string",
"description": "Top-tier agency slug"
}
},
"description": "Awarding agency hierarchy",
"additionalProperties": false
},
"total_loan_value": {
"type": "number",
"description": "Face value of the loan in USD (category \"loans\" only). A loan reports its value here, not in total_obligation, which is often 0."
},
"total_obligation": {
"type": "number",
"description": "Total obligation amount in USD"
},
"type_description": {
"type": "string",
"description": "Human-readable award type"
},
"total_subsidy_cost": {
"type": "number",
"description": "Estimated cost to the government of the loan subsidy in USD (category \"loans\" only)"
},
"assistance_listings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Assistance Listing program title"
},
"number": {
"type": "string",
"description": "Assistance Listing (CFDA) number, e.g. 93.855 — usable in usaspending_search_awards assistance_listings"
},
"obligation": {
"type": "number",
"description": "Federal obligation in USD made under this listing"
}
},
"description": "One Assistance Listing funding the award",
"additionalProperties": false
},
"description": "Every Assistance Listing (CFDA program) funding the award, in upstream order; absent for contracts and IDVs"
},
"place_of_performance": {
"type": "object",
"properties": {
"zip5": {
"type": "string",
"description": "ZIP code of performance"
},
"city_name": {
"type": "string",
"description": "City of performance"
},
"state_code": {
"type": "string",
"description": "State code of performance"
},
"county_name": {
"type": "string",
"description": "County of performance"
},
"country_code": {
"type": "string",
"description": "Three-letter country code of performance (e.g. USA)"
},
"congressional_code": {
"type": "string",
"description": "Congressional district of performance, preserving leading zeros"
}
},
"description": "Place of performance; absent when upstream reports no location fields",
"additionalProperties": false
},
"total_account_outlay": {
"type": "number",
"description": "Total federal-account outlay in USD"
},
"period_of_performance": {
"type": "object",
"properties": {
"end_date": {
"type": "string",
"description": "Performance end date (YYYY-MM-DD)"
},
"start_date": {
"type": "string",
"description": "Performance start date (YYYY-MM-DD)"
},
"potential_end_date": {
"type": "string",
"description": "Potential end date including options (YYYY-MM-DD)"
}
},
"description": "Period of performance dates",
"additionalProperties": false
},
"base_exercised_options": {
"type": "number",
"description": "Base and exercised options value in USD when reported for contracts or IDVs"
},
"account_outlays_by_defc": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "DEF code identifying the emergency supplemental"
},
"amount": {
"type": "number",
"description": "Outlay amount in USD for this DEF code"
}
},
"description": "DEF code entry with code and outlay amount",
"additionalProperties": false
},
"description": "Federal-account outlays by Disaster/Emergency Funding code in upstream order"
},
"product_or_service_code": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "PSC product or service code"
},
"description": {
"type": "string",
"description": "PSC description"
}
},
"description": "Product or service code (contracts)",
"additionalProperties": false
},
"total_account_obligation": {
"type": "number",
"description": "Total federal-account obligation in USD"
},
"generated_unique_award_id": {
"type": "string",
"description": "Generated unique award ID"
},
"base_and_all_options_value": {
"type": "number",
"description": "Base and all options value in USD (contracts)"
},
"account_obligations_by_defc": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "DEF code identifying the emergency supplemental"
},
"amount": {
"type": "number",
"description": "Obligation amount in USD for this DEF code"
}
},
"description": "DEF code entry with code and obligation amount",
"additionalProperties": false
},
"description": "Funding breakdown by Disaster/Emergency Funding (DEF) code — links to disaster appropriations"
}
},
"additionalProperties": false
}usaspending_get_award annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_get_award_transactions — Get Award Transactions
Advertised read-only
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).
usaspending_get_award_transactions input schema
{
"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
}usaspending_get_award_transactions output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"award_id",
"results",
"page_metadata",
"queried_award_id",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Guidance when no transactions were returned — helps confirm the award_id is a valid generated_internal_id. Absent when results are present."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Generated transaction ID (ASST_TX or CONT_TX)"
},
"type": {
"type": "string",
"description": "Transaction type code"
},
"action_date": {
"type": "string",
"description": "Transaction action date (YYYY-MM-DD)"
},
"action_type": {
"type": "string",
"description": "Action type code"
},
"cfda_number": {
"type": "string",
"description": "Assistance Listing (CFDA) number for assistance transactions"
},
"description": {
"type": "string",
"description": "Transaction description"
},
"type_description": {
"type": "string",
"description": "Transaction type description"
},
"modification_number": {
"type": "string",
"description": "Modification number or amendment"
},
"action_type_description": {
"type": "string",
"description": "Action type description"
},
"face_value_loan_guarantee": {
"type": "number",
"description": "Loan face value in USD; absent for non-loan transactions"
},
"federal_action_obligation": {
"type": "number",
"description": "Obligation change in USD for this transaction (positive = increase, negative = deobligation)"
},
"original_loan_subsidy_cost": {
"type": "number",
"description": "Original loan subsidy cost in USD; absent for non-loan transactions"
}
},
"description": "Transaction record with modification details and obligation change",
"additionalProperties": false
},
"description": "List of transactions for this award"
},
"award_id": {
"type": "string",
"description": "Award ID queried"
},
"totalCount": {
"type": "number",
"description": "Total transaction count across all pages (when available)"
},
"current_page": {
"type": "number",
"description": "Current page returned"
},
"has_next_page": {
"type": "boolean",
"description": "Whether there are more pages of transactions"
},
"page_metadata": {
"type": "object",
"required": [
"has_next",
"page",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page"
},
"limit": {
"type": "number",
"description": "Transactions per page"
},
"total": {
"type": "number",
"description": "Total transaction count"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages"
}
},
"description": "Pagination metadata",
"additionalProperties": false
},
"queried_award_id": {
"type": "string",
"description": "Award ID whose transactions were listed"
}
},
"additionalProperties": false
}usaspending_get_award_transactions annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_get_award_subawards — Get Award Subawards
Advertised read-only
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.
usaspending_get_award_subawards input schema
{
"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
}usaspending_get_award_subawards output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"award_id",
"results",
"page_metadata",
"prime_award_id",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Guidance when no subawards were returned — suggests checking subaward_count from usaspending_get_award first. Absent when results are present."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Subaward internal ID"
},
"amount": {
"type": "number",
"description": "Subaward amount in USD"
},
"action_date": {
"type": "string",
"description": "Subaward action date (YYYY-MM-DD)"
},
"description": {
"type": "string",
"description": "Subaward description"
},
"recipient_name": {
"type": "string",
"description": "Subcontractor or sub-grantee name"
},
"subaward_number": {
"type": "string",
"description": "Subaward number or identifier"
}
},
"description": "Subaward record with identifier, amount, recipient, date, and description",
"additionalProperties": false
},
"description": "List of subawards under this prime award"
},
"award_id": {
"type": "string",
"description": "Prime award ID queried"
},
"totalCount": {
"type": "number",
"description": "Total subaward count across all pages (when available)"
},
"current_page": {
"type": "number",
"description": "Current page returned"
},
"has_next_page": {
"type": "boolean",
"description": "Whether there are more pages of subawards"
},
"page_metadata": {
"type": "object",
"required": [
"has_next",
"page",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page"
},
"limit": {
"type": "number",
"description": "Subawards per page"
},
"total": {
"type": "number",
"description": "Total subaward count"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages"
}
},
"description": "Pagination metadata",
"additionalProperties": false
},
"prime_award_id": {
"type": "string",
"description": "Prime award ID whose subawards were listed"
}
},
"additionalProperties": false
}usaspending_get_award_subawards annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_get_award_federal_accounts — Get Award Federal Accounts
Advertised read-only
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.
usaspending_get_award_federal_accounts input schema
{
"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
}usaspending_get_award_federal_accounts output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"award_id",
"results",
"page_metadata",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Recovery for an empty page, distinguished from a known zero total; absent when results are present."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"account_title": {
"type": "string",
"description": "Full federal account title"
},
"federal_account": {
"type": "string",
"description": "Federal account code in AGENCY-MAIN format (e.g., 080-0120) — pass to usaspending_get_federal_account as account_code for the account budget detail"
},
"funding_agency_id": {
"type": "number",
"description": "Internal USAspending database ID of the funding agency — not the toptier code accepted by usaspending_get_agency"
},
"funding_agency_name": {
"type": "string",
"description": "Name of the funding agency"
},
"funding_agency_slug": {
"type": "string",
"description": "Funding agency slug (e.g., \"national-aeronautics-and-space-administration\") — pass to usaspending_get_agency as agency_slug"
},
"funding_toptier_agency_id": {
"type": "number",
"description": "Internal USAspending database ID of the funding toptier agency — distinct from the directory toptier_code accepted by usaspending_get_agency"
},
"funding_agency_abbreviation": {
"type": "string",
"description": "Abbreviation of the funding agency (e.g., \"NASA\")"
},
"total_transaction_obligated_amount": {
"type": "number",
"description": "Amount obligated to this award from this federal account in USD"
}
},
"description": "Federal account that funded this award, with obligation and funding agency",
"additionalProperties": false
},
"description": "Federal accounts funding this award"
},
"award_id": {
"type": "string",
"description": "Award ID queried"
},
"totalCount": {
"type": "number",
"description": "Total number of funding accounts across all pages (when available)"
},
"current_page": {
"type": "number",
"description": "Current page returned"
},
"has_next_page": {
"type": "boolean",
"description": "Whether there are more pages of funding accounts"
},
"page_metadata": {
"type": "object",
"required": [
"page",
"has_next",
"has_previous",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page number"
},
"count": {
"type": "number",
"description": "Total funding accounts across all pages"
},
"limit": {
"type": "number",
"description": "Results per page"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages of results"
},
"has_previous": {
"type": "boolean",
"description": "Whether there are previous pages"
}
},
"description": "Pagination metadata",
"additionalProperties": false
}
},
"additionalProperties": false
}usaspending_get_award_federal_accounts annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_get_idv_awards — Get IDV Child Awards
Advertised read-only
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.
usaspending_get_idv_awards input schema
{
"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": [
"award_type",
"description",
"funding_agency",
"awarding_agency",
"last_date_to_order",
"obligated_amount",
"period_of_performance_current_end_date",
"period_of_performance_start_date",
"piid"
],
"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
}usaspending_get_idv_awards output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"award_id",
"results",
"page_metadata",
"parent_award_id",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The per-page limit that was applied, when truncated."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of child awards returned on this page, when truncated."
},
"notice": {
"type": "string",
"description": "How to continue when truncated, or a recovery hint when results are empty — the award may have no children of the requested type. Absent otherwise."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"piid": {
"type": "string",
"description": "Procurement Instrument Identifier"
},
"award_type": {
"type": "string",
"description": "Award type (e.g., \"DELIVERY ORDER\")"
},
"description": {
"type": "string",
"description": "Award description"
},
"funding_agency": {
"type": "string",
"description": "Name of the funding agency"
},
"awarding_agency": {
"type": "string",
"description": "Name of the awarding agency"
},
"obligated_amount": {
"type": "number",
"description": "Total obligated amount in USD"
},
"last_date_to_order": {
"type": "string",
"description": "Last date to place orders against this IDV (YYYY-MM-DD, nullable)"
},
"generated_unique_award_id": {
"type": "string",
"description": "Generated unique award ID for this child award — pass to usaspending_get_award to fetch full details"
},
"period_of_performance_start_date": {
"type": "string",
"description": "Performance start date (YYYY-MM-DD)"
},
"period_of_performance_current_end_date": {
"type": "string",
"description": "Performance current end date (YYYY-MM-DD)"
}
},
"description": "Child award record with ID, amounts, agencies, and performance dates",
"additionalProperties": false
},
"description": "Child awards placed under this IDV"
},
"award_id": {
"type": "string",
"description": "Parent IDV award ID queried"
},
"truncated": {
"type": "boolean",
"description": "True when the upstream reports more child awards beyond this page. Absent on a full page the upstream marks as last — has_next_page still says whether to request another."
},
"current_page": {
"type": "number",
"description": "Current page returned"
},
"has_next_page": {
"type": "boolean",
"description": "Whether more pages of child awards may remain — set on a full page even when the upstream flag reports none."
},
"page_metadata": {
"type": "object",
"required": [
"has_next",
"has_previous",
"page",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page number"
},
"limit": {
"type": "number",
"description": "Results per page"
},
"has_next": {
"type": "boolean",
"description": "Whether more child awards may remain — true on a full page even when the upstream flag reports none (this endpoint returns no total). A short or empty page marks the end."
},
"has_previous": {
"type": "boolean",
"description": "Whether there are previous pages"
}
},
"description": "Pagination metadata (no total count available from this endpoint)",
"additionalProperties": false
},
"parent_award_id": {
"type": "string",
"description": "Parent IDV award ID whose children were listed"
}
},
"additionalProperties": false
}usaspending_get_idv_awards annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_search_recipients — Search Award Recipients
Advertised read-onlyOpen-world
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.
usaspending_search_recipients input schema
{
"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
}usaspending_search_recipients output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"page_metadata",
"recipient_count",
"page",
"has_next"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "number",
"description": "Current page number returned"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Blank-keyword disclosure and pagination recovery. An empty page is distinguished from a known zero total; absent when no notice applies."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient hexadecimal 8-4-4-4-12 hash with level suffix: -P parent, -C child, -R standalone — pass to usaspending_get_recipient for full profile"
},
"uei": {
"type": "string",
"description": "Unique Entity Identifier (SAM.gov)"
},
"duns": {
"type": "string",
"description": "DUNS number (legacy, being phased out)"
},
"name": {
"type": "string",
"description": "Recipient legal business name"
},
"amount": {
"type": "number",
"description": "Total award amount in USD for the selected award type"
},
"recipient_level": {
"type": "string",
"description": "Hierarchy level: P = parent, C = child, R = standalone"
}
},
"description": "Recipient entry with ID, name, and award totals",
"additionalProperties": false
},
"description": "Matching recipients"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages of results"
},
"totalCount": {
"type": "number",
"description": "Total matching recipients across all pages"
},
"page_metadata": {
"type": "object",
"required": [
"page",
"has_next",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page number"
},
"limit": {
"type": "number",
"description": "Results per page"
},
"total": {
"type": "number",
"description": "Total matching recipients across all pages"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages of results"
}
},
"description": "Pagination metadata — page through with the page input to reach later matches",
"additionalProperties": false
},
"recipient_count": {
"type": "number",
"description": "Number of matching recipients returned on this page"
}
},
"additionalProperties": false
}usaspending_search_recipients annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}usaspending_get_recipient — Get Recipient Profile
Advertised read-only
Fetch a recipient's full profile including address, business type codes, parent organization, alternate names, and total transaction and loan amounts. Recipient IDs are hexadecimal 8-4-4-4-12 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.
usaspending_get_recipient input schema
{
"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 hexadecimal 8-4-4-4-12 hash with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P — from usaspending_search_recipients or usaspending_get_award"
}
},
"additionalProperties": false
}usaspending_get_recipient output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"period"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"uei": {
"type": "string",
"description": "Unique Entity Identifier (SAM.gov)"
},
"duns": {
"type": "string",
"description": "DUNS number (legacy)"
},
"name": {
"type": "string",
"description": "Recipient legal business name"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"recipient_not_found",
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `recipient_not_found`: No recipient found for the given recipient ID. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"period": {
"type": "string",
"description": "Window the totals cover: FY<year> when fiscal_year was given, otherwise \"trailing 12 months\""
},
"location": {
"type": "object",
"properties": {
"zip": {
"type": "string",
"description": "ZIP code"
},
"zip4": {
"type": "string",
"description": "ZIP+4 extension"
},
"city_name": {
"type": "string",
"description": "City"
},
"state_code": {
"type": "string",
"description": "State code"
},
"country_code": {
"type": "string",
"description": "Country code"
},
"address_line1": {
"type": "string",
"description": "Street address line 1"
},
"address_line2": {
"type": "string",
"description": "Street address line 2"
}
},
"description": "Recipient address",
"additionalProperties": false
},
"parent_uei": {
"type": "string",
"description": "Parent organization UEI"
},
"parent_name": {
"type": "string",
"description": "Parent organization name"
},
"recipient_id": {
"type": "string",
"description": "Recipient hash ID"
},
"business_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Business type codes"
},
"alternate_names": {
"type": "array",
"items": {
"type": "string"
},
"description": "Alternate business names"
},
"recipient_level": {
"type": "string",
"description": "Hierarchy level: P = parent, C = child, R = standalone"
},
"total_transactions": {
"type": "number",
"description": "Total number of award transactions over period"
},
"total_transaction_amount": {
"type": "number",
"description": "Total transaction (award) amount in USD over period, across all award types"
},
"total_face_value_loan_amount": {
"type": "number",
"description": "Total face value of loans in USD over period"
},
"total_face_value_loan_transactions": {
"type": "number",
"description": "Number of face-value loan transactions over period"
}
},
"additionalProperties": false
}usaspending_get_recipient annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_get_agency — Get Agency Overview
Advertised read-only
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 directory toptier_code (e.g., 097 for DoD, 1601 for Labor; one/two-digit numeric inputs are zero-padded to three digits) 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.
usaspending_get_agency input schema
{
"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": "Directory toptier agency code (e.g., 097, 012, 1601) from usaspending_list_agencies. One/two-digit numeric values are padded to three digits (80 becomes 080); three/four-digit codes are preserved. Use either toptier_code or agency_slug, not both."
}
},
"additionalProperties": false
}usaspending_get_agency output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"name": {
"type": "string",
"description": "Agency full name"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"agency_not_found",
"missing_input",
"conflicting_input",
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `agency_not_found`: No agency found for the given toptier_code or agency_slug. `missing_input`: Neither toptier_code nor agency_slug was provided. `conflicting_input`: Both toptier_code and agency_slug were provided. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "How to page for more sub-agencies when the breakdown is truncated, and which sections failed to load and whether a retry may recover them. Absent when neither applies."
},
"mission": {
"type": "string",
"description": "Agency mission statement"
},
"website": {
"type": "string",
"description": "Agency website URL"
},
"agency_id": {
"type": "number",
"description": "Internal agency ID"
},
"def_codes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "DEF code identifying an emergency supplemental"
},
"title": {
"type": "string",
"description": "Emergency or disaster title"
},
"public_law": {
"type": "string",
"description": "Public law number"
}
},
"description": "DEF code entry with public law and title",
"additionalProperties": false
},
"description": "Disaster/Emergency Funding (DEF) codes applicable to this agency"
},
"fiscal_year": {
"type": "number",
"description": "Fiscal year the budgetary totals below reflect: the most recent year with reported budget data, which can trail the current fiscal year (a new year has no amounts until the agency first reports in it)"
},
"abbreviation": {
"type": "string",
"description": "Agency abbreviation"
},
"sub_agencies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Sub-agency name"
},
"abbreviation": {
"type": "string",
"description": "Sub-agency abbreviation"
},
"new_award_count": {
"type": "number",
"description": "New awards count"
},
"total_obligations": {
"type": "number",
"description": "Sub-agency obligation total in USD"
},
"transaction_count": {
"type": "number",
"description": "Sub-agency transaction count"
}
},
"description": "Sub-agency entry with obligations and transaction counts",
"additionalProperties": false
},
"description": "Sub-agency breakdown within this toptier agency (one page)"
},
"toptier_code": {
"type": "string",
"description": "Directory toptier agency code, which can have three or four digits"
},
"outlay_amount": {
"type": "number",
"description": "Total outlays in USD for the fiscal year"
},
"sub_agency_page": {
"type": "number",
"description": "Current sub-agency page returned. Absent when the sub-agency request failed."
},
"obligated_amount": {
"type": "number",
"description": "Total amount obligated in USD for the fiscal year"
},
"sub_agency_total": {
"type": "number",
"description": "Total sub-agencies across all pages (when available)"
},
"subtier_agency_count": {
"type": "number",
"description": "Number of sub-agencies within this toptier agency"
},
"unavailable_sections": {
"type": "array",
"items": {
"type": "object",
"required": [
"section",
"reason",
"retryable",
"message"
],
"properties": {
"reason": {
"enum": [
"api_unavailable",
"api_timeout",
"upstream_error"
],
"type": "string",
"description": "api_unavailable: USAspending was unreachable or answered with a server error. api_timeout: no answer before the request deadline. upstream_error: USAspending rejected the request."
},
"message": {
"type": "string",
"description": "The failure message for this section."
},
"section": {
"enum": [
"budgetary_resources",
"sub_agencies"
],
"type": "string",
"description": "budgetary_resources: fiscal_year and the budget, obligation, and outlay totals. sub_agencies: the sub-agency breakdown and its pagination."
},
"retryable": {
"type": "boolean",
"description": "Whether retrying the call may load this section."
}
},
"description": "A section omitted from the result because its request failed",
"additionalProperties": false
},
"description": "Sections omitted because their request failed while the agency overview loaded. Absent when every section loaded."
},
"has_more_sub_agencies": {
"type": "boolean",
"description": "Whether more sub-agency pages are available. Absent when the sub-agency request failed, since pagination is then unknown."
},
"sub_agency_fiscal_year": {
"type": "number",
"description": "Fiscal year the sub-agency breakdown covers, as upstream reports it: the same year as fiscal_year, or the current fiscal year when no budget year was available within 5 seconds — so it can differ from fiscal_year even when both are present. Absent when the sub-agency request failed, or when upstream reports no year for a breakdown requested without one."
},
"sub_agency_page_metadata": {
"type": "object",
"required": [
"page",
"has_next",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current sub-agency page number"
},
"limit": {
"type": "number",
"description": "Sub-agencies per page"
},
"total": {
"type": "number",
"description": "Total sub-agencies across all pages"
},
"has_next": {
"type": "boolean",
"description": "Whether more sub-agency pages are available"
}
},
"description": "Pagination metadata for the sub-agency breakdown",
"additionalProperties": false
},
"budgetary_resources_amount": {
"type": "number",
"description": "Total budgetary resources in USD for the fiscal year"
}
},
"additionalProperties": false
}usaspending_get_agency annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_spending_by_geography — Spending by Geography
Advertised read-onlyOpen-world
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.
usaspending_spending_by_geography input schema
{
"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 filters; each effective term needs at least three characters, including significant whitespace"
},
"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 codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated"
},
"recipient_id": {
"type": "string",
"description": "recipient_id from usaspending_search_recipients: hexadecimal 8-4-4-4-12 hash plus uppercase -P, -C, or -R; hash letters normalize to lowercase; empty is unset"
},
"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
}usaspending_spending_by_geography output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"scope",
"geo_layer",
"results",
"total",
"total_areas_available",
"applied_scope",
"applied_geo_layer",
"area_count"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit that was applied."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_keyword",
"invalid_naics_code",
"invalid_recipient_id",
"api_unavailable",
"api_timeout",
"date_range_inverted",
"date_before_earliest",
"assistance_listings_type_mismatch",
"psc_codes_type_mismatch"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_keyword`: An effective keyword has fewer than three characters. `invalid_naics_code`: An effective NAICS code is known to be invalid. `invalid_recipient_id`: An active analytics recipient_id is malformed. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. `date_range_inverted`: Both filters.time_period_start and filters.time_period_end were supplied and the start falls after the end. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. `assistance_listings_type_mismatch`: filters.assistance_listings was given while every code in filters.award_type_codes is a contract or IDV code. `psc_codes_type_mismatch`: filters.psc_codes was given while every code in filters.award_type_codes is an assistance code. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"scope": {
"type": "string",
"description": "Location scope used for aggregation"
},
"shown": {
"type": "number",
"description": "Number of geographic areas returned."
},
"total": {
"type": "number",
"description": "Number of geographic areas returned"
},
"notice": {
"type": "string",
"description": "How to reach areas omitted by limit, which shape_codes matched no area, which time-period bound was filled in when only the other was supplied, and — when the filters matched no area — any Assistance Listing, PSC, or DEF codes sent and how to broaden filters. Absent when none applies."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"per_capita": {
"type": "number",
"description": "Per-capita obligation amount in USD (aggregated_amount / population)"
},
"population": {
"type": "number",
"description": "Population of the geographic area (when available)"
},
"shape_code": {
"type": "string",
"description": "Area code, the form shape_codes takes: 2-letter postal code (state), 5-digit state + county FIPS (county), or 4-digit state FIPS + district number (district). Absent on the row for spending with no recorded location."
},
"display_name": {
"type": "string",
"description": "Human-readable name for the geographic area"
},
"aggregated_amount": {
"type": "number",
"description": "Total obligation amount in USD for this geographic area"
}
},
"description": "Geographic area with spending totals and optional per-capita data",
"additionalProperties": false
},
"description": "Spending totals by geographic area"
},
"geo_layer": {
"type": "string",
"description": "Geographic granularity used"
},
"truncated": {
"type": "boolean",
"description": "True when the area list was capped at limit."
},
"area_count": {
"type": "number",
"description": "Number of geographic areas returned"
},
"applied_scope": {
"type": "string",
"description": "Location scope applied: place_of_performance or recipient_location"
},
"applied_keywords": {
"type": "string",
"description": "Keyword filters applied (comma-separated)"
},
"applied_def_codes": {
"type": "string",
"description": "DEF codes sent, uppercased (comma-separated)"
},
"applied_geo_layer": {
"type": "string",
"description": "Geographic granularity applied: state, county, or district"
},
"applied_psc_codes": {
"type": "string",
"description": "PSC codes sent, uppercased (comma-separated)"
},
"truncationCeiling": {
"type": "number",
"description": "Obligation amount of the lowest-ranked area shown — an upper bound on omitted ones."
},
"applied_agency_name": {
"type": "string",
"description": "Awarding agency name filter applied"
},
"applied_naics_codes": {
"type": "string",
"description": "NAICS code filters applied (comma-separated)"
},
"applied_shape_codes": {
"type": "string",
"description": "Area codes listed in shape_codes, letters uppercased and duplicates removed (comma-separated)"
},
"applied_recipient_id": {
"type": "string",
"description": "Normalized recipient hash and level sent"
},
"total_areas_available": {
"type": "number",
"description": "Number of geographic areas the filters matched, before shape_codes selection and limit were applied"
},
"applied_time_period_end": {
"type": "string",
"description": "End of the time period sent (YYYY-MM-DD), including a filled-in end"
},
"applied_time_period_start": {
"type": "string",
"description": "Start of the time period sent (YYYY-MM-DD), including a filled-in start"
},
"applied_award_type_default": {
"type": "string",
"description": "Disclosure that no filters were supplied, so award_type_codes defaulted to the complete set. Absent when the caller supplied at least one filter."
},
"applied_assistance_listings": {
"type": "string",
"description": "Assistance Listing numbers sent (comma-separated)"
}
},
"additionalProperties": false
}usaspending_spending_by_geography annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}usaspending_spending_by_category — Spending by Category
Advertised read-onlyOpen-world
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.
usaspending_spending_by_category input schema
{
"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; each effective term needs at least three characters, including significant whitespace"
},
"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 codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated"
},
"recipient_id": {
"type": "string",
"description": "recipient_id from usaspending_search_recipients: hexadecimal 8-4-4-4-12 hash plus uppercase -P, -C, or -R; hash letters normalize to lowercase; empty is unset"
},
"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
}usaspending_spending_by_category output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"category",
"results",
"page_metadata",
"page",
"has_next"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "number",
"description": "Current page returned"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_keyword",
"invalid_naics_code",
"invalid_recipient_id",
"api_unavailable",
"api_timeout",
"date_range_inverted",
"date_before_earliest",
"assistance_listings_type_mismatch",
"psc_codes_type_mismatch"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_keyword`: An effective keyword has fewer than three characters. `invalid_naics_code`: An effective NAICS code is known to be invalid. `invalid_recipient_id`: An active analytics recipient_id is malformed. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. `date_range_inverted`: Both filters.time_period_start and filters.time_period_end were supplied and the start falls after the end. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. `assistance_listings_type_mismatch`: filters.assistance_listings was given while every code in filters.award_type_codes is a contract or IDV code. `psc_codes_type_mismatch`: filters.psc_codes was given while every code in filters.award_type_codes is an assistance code. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Names a date bound that was filled in because only the other was supplied, and — when results are empty — names any Assistance Listing, PSC, or DEF codes sent and suggests how to broaden filters. Absent when neither applies."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Item identifier (varies by category)"
},
"uei": {
"type": "string",
"description": "Recipient Unique Entity Identifier (recipient_duns rows). Absent when upstream has none."
},
"code": {
"type": "string",
"description": "Code value (NAICS, PSC, CFDA number, recipient DUNS, etc.)"
},
"name": {
"type": "string",
"description": "Item name or description"
},
"amount": {
"type": "number",
"description": "Total obligation amount in USD"
},
"recipient_id": {
"type": "string",
"description": "Recipient hash ID (recipient_duns rows) — pass to usaspending_get_recipient for the profile. Absent when upstream has none."
}
},
"description": "Category item with code, name, and obligation amount",
"additionalProperties": false
},
"description": "Top items in this category by obligation amount"
},
"category": {
"type": "string",
"description": "Breakdown dimension used"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages"
},
"totalCount": {
"type": "number",
"description": "Total number of items in this category (when available)"
},
"page_metadata": {
"type": "object",
"required": [
"has_next",
"page",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page"
},
"limit": {
"type": "number",
"description": "Items per page"
},
"total": {
"type": "number",
"description": "Total items"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages"
}
},
"description": "Pagination metadata",
"additionalProperties": false
},
"applied_keywords": {
"type": "string",
"description": "Keyword filters applied (comma-separated)"
},
"applied_def_codes": {
"type": "string",
"description": "DEF codes sent, uppercased (comma-separated)"
},
"applied_psc_codes": {
"type": "string",
"description": "PSC codes sent, uppercased (comma-separated)"
},
"applied_agency_name": {
"type": "string",
"description": "Awarding agency name filter applied"
},
"applied_naics_codes": {
"type": "string",
"description": "NAICS code filters applied (comma-separated)"
},
"applied_recipient_id": {
"type": "string",
"description": "Normalized recipient hash and level sent"
},
"applied_time_period_end": {
"type": "string",
"description": "End date sent (YYYY-MM-DD), including a filled-in end"
},
"applied_time_period_start": {
"type": "string",
"description": "Start date sent (YYYY-MM-DD), including a filled-in start"
},
"applied_assistance_listings": {
"type": "string",
"description": "Assistance Listing numbers sent (comma-separated)"
}
},
"additionalProperties": false
}usaspending_spending_by_category annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}usaspending_spending_over_time — Spending Over Time
Advertised read-onlyOpen-world
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).
usaspending_spending_over_time input schema
{
"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; each effective term needs at least three characters, including significant whitespace"
},
"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 codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated"
},
"recipient_id": {
"type": "string",
"description": "recipient_id from usaspending_search_recipients: hexadecimal 8-4-4-4-12 hash plus uppercase -P, -C, or -R; hash letters normalize to lowercase; empty is unset"
},
"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
}usaspending_spending_over_time output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"group",
"results",
"total_periods",
"applied_award_type_codes",
"time_group",
"period_count"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_keyword",
"invalid_naics_code",
"invalid_recipient_id",
"api_unavailable",
"api_timeout",
"date_range_inverted",
"date_before_earliest",
"assistance_listings_type_mismatch",
"psc_codes_type_mismatch"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_keyword`: An effective keyword has fewer than three characters. `invalid_naics_code`: An effective NAICS code is known to be invalid. `invalid_recipient_id`: An active analytics recipient_id is malformed. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. `date_range_inverted`: Both filters.time_period_start and filters.time_period_end were supplied and the start falls after the end. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. `assistance_listings_type_mismatch`: filters.assistance_listings was given while every code in filters.award_type_codes is a contract or IDV code, or award_type_codes was left at its contract default. `psc_codes_type_mismatch`: filters.psc_codes was given while every code in filters.award_type_codes is an assistance code. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"group": {
"type": "string",
"description": "Time grouping used"
},
"notice": {
"type": "string",
"description": "Discloses effective award-type scope, composes any filled time-window bound, and names active code/recipient filters when no periods are returned."
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"time_period"
],
"properties": {
"idvs": {
"type": "number",
"description": "IDV (Indefinite Delivery Vehicle) obligation amount in USD for this period"
},
"loans": {
"type": "number",
"description": "Loan obligation amount in USD for this period"
},
"other": {
"type": "number",
"description": "Other financial assistance obligation amount in USD for this period"
},
"grants": {
"type": "number",
"description": "Grant obligation amount in USD for this period"
},
"contracts": {
"type": "number",
"description": "Contract obligation amount in USD for this period"
},
"time_period": {
"type": "object",
"properties": {
"month": {
"type": "string",
"description": "Fiscal month: an ordinal within fiscal_year, 1–12, where 1 = October and 12 = September. Fiscal month 1 of FY2025 is October 2024 — not January."
},
"quarter": {
"type": "string",
"description": "Fiscal quarter (1–4)"
},
"fiscal_year": {
"type": "string",
"description": "Fiscal year (e.g., 2024)"
}
},
"description": "Time period for this row. Populated per the requested grouping: fiscal_year alone, fiscal_year + quarter, or fiscal_year + month.",
"additionalProperties": false
},
"direct_payments": {
"type": "number",
"description": "Direct payment obligation amount in USD for this period"
},
"aggregated_amount": {
"type": "number",
"description": "Total obligation amount in USD for this period"
}
},
"description": "Time period row with total obligations and optional award-type breakdowns, all restricted to applied_award_type_codes; an excluded category is not an agency-wide zero",
"additionalProperties": false
},
"description": "Time-series of obligation totals"
},
"time_group": {
"type": "string",
"description": "Time grouping applied: fiscal_year, quarter, or month"
},
"period_count": {
"type": "number",
"description": "Number of time periods returned"
},
"total_periods": {
"type": "number",
"description": "Number of time periods returned"
},
"applied_keywords": {
"type": "string",
"description": "Keyword filters applied (comma-separated)"
},
"applied_def_codes": {
"type": "string",
"description": "DEF codes sent, uppercased (comma-separated)"
},
"applied_psc_codes": {
"type": "string",
"description": "PSC codes sent, uppercased (comma-separated)"
},
"applied_agency_name": {
"type": "string",
"description": "Awarding agency name filter applied"
},
"applied_naics_codes": {
"type": "string",
"description": "NAICS code filters applied (comma-separated)"
},
"applied_recipient_id": {
"type": "string",
"description": "Normalized recipient hash and level sent"
},
"applied_time_period_end": {
"type": "string",
"description": "End of the time window sent (YYYY-MM-DD), including a filled-in end"
},
"applied_award_type_codes": {
"type": "string",
"description": "Effective award type codes sent (comma-separated); totals and every breakdown cover only these codes"
},
"applied_time_period_start": {
"type": "string",
"description": "Start of the time window sent (YYYY-MM-DD), including a filled-in start"
},
"applied_award_type_default": {
"type": "string",
"const": "contracts",
"description": "Present only when omitted or empty codes select the contract default"
},
"applied_assistance_listings": {
"type": "string",
"description": "Assistance Listing numbers sent (comma-separated)"
}
},
"additionalProperties": false
}usaspending_spending_over_time annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}usaspending_disaster_spending — Disaster and Emergency Spending
Advertised read-onlyOpen-world
Fetch disaster and emergency supplemental spending broken down by agency, CFDA assistance program, recipient, or geography, or request an overview. Filter by DEF codes to select emergency appropriations, then check amount_coverage before interpreting amounts: award breakdowns and geography cover the provider COVID grouping, while overview and agency total cover all requested codes. Rows and award counts can match codes outside the monetary scope. DEF codes appear in usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields.
usaspending_disaster_spending input schema
{
"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). Breakdowns rank obligations descending before pagination; geography ranks aggregated_amount. Agency award without award_type_codes collects all provider pages before ranking, so a smaller limit does not reduce that upstream work. 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",
"pattern": "^[0-9A-Za-z]{1,3}$",
"description": "Disaster Emergency Fund Code, e.g. Z or L"
},
"description": "DEF codes, 1–3 letters or digits, sent uppercased. Optional for overview; required for breakdowns. Amount coverage is reported separately: award breakdowns and geography aggregate only the provider COVID grouping; matching rows and counts may include other codes. Overview and agency total cover all requested codes. Find codes 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
}usaspending_disaster_spending output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dimension",
"spending_type",
"results",
"applied_dimension"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "recipient: the result-set ceiling the upstream applied. geography: the page size (limit)."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"missing_def_codes",
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `missing_def_codes`: A non-overview dimension has no DEF codes. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of results returned on this page."
},
"notice": {
"type": "string",
"description": "Upstream messages, ignored filters, empty-page recovery, and guidance for recipient ceilings or remaining geography areas."
},
"totals": {
"type": "object",
"properties": {
"outlay": {
"type": "number",
"description": "Outlays in USD across the matching result set, within amount_coverage"
},
"obligation": {
"type": "number",
"description": "Obligations in USD across the matching result set, within amount_coverage"
},
"award_count": {
"type": "number",
"description": "Number of awards across the result set (award-level breakdowns)"
},
"total_budgetary_resources": {
"type": "number",
"description": "Total budgetary resources in USD across the result set (agency dimension with spending_type total)"
}
},
"description": "Totals across every matching row, as reported upstream — not a sum of this page. Present for the agency, cfda, and recipient dimensions; the members depend on dimension and spending_type. Absent for overview and geography.",
"additionalProperties": false
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Item ID. On the recipient dimension, a recipient hash ID for usaspending_get_recipient — the recipient-level (-R) ID when the recipient has several."
},
"code": {
"type": "string",
"description": "Code (agency code, CFDA number, DEF code, etc.)"
},
"name": {
"type": "string",
"description": "Item name or description"
},
"outlay": {
"type": "number",
"description": "Outlay amount in USD"
},
"obligation": {
"type": "number",
"description": "Obligation amount in USD"
},
"per_capita": {
"type": "number",
"description": "Obligation-based spending per capita in USD (geography dimension)"
},
"population": {
"type": "number",
"description": "Population of the geographic area (geography dimension)"
},
"shape_code": {
"type": "string",
"description": "Geographic code (geography dimension). Absent on the unattributed row: spending with no recorded place of performance, which still ranks and counts as an area."
},
"award_count": {
"type": "number",
"description": "Number of awards"
},
"display_name": {
"type": "string",
"description": "Geographic display name (geography dimension); absent on the unattributed row"
},
"aggregated_amount": {
"type": "number",
"description": "Obligation-based spending amount in USD (geography dimension)"
},
"face_value_of_loan": {
"type": "number",
"description": "Face value of loan guarantees in USD (loans spending_type)"
},
"total_budgetary_resources": {
"type": "number",
"description": "Total budgetary resources in USD for this row (agency dimension with spending_type total)"
}
},
"description": "Disaster spending breakdown entry by dimension (agency, CFDA, recipient, or geography)",
"additionalProperties": false
},
"description": "Breakdown results (empty for overview dimension)"
},
"overview": {
"type": "object",
"properties": {
"award_outlays": {
"type": "number",
"description": "Total award outlays in USD"
},
"total_outlays": {
"type": "number",
"description": "Total outlays in USD"
},
"award_obligations": {
"type": "number",
"description": "Total award obligations in USD"
},
"total_obligations": {
"type": "number",
"description": "Total obligations in USD"
},
"face_value_of_loans": {
"type": "number",
"description": "Face value of loan guarantees in USD"
},
"funding_by_def_code": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "DEF code label or title"
},
"amount": {
"type": "number",
"description": "Funding amount in USD for this DEF code"
},
"def_code": {
"type": "string",
"description": "DEF code"
},
"public_law": {
"type": "string",
"description": "Public law number"
}
},
"description": "DEF code funding entry with amount and public law reference",
"additionalProperties": false
},
"description": "Funding amounts broken down by DEF code (emergency appropriation)"
},
"unobligated_balance": {
"type": "number",
"description": "Unobligated balance in USD"
},
"total_budget_authority": {
"type": "number",
"description": "Total budget authority in USD across all emergency supplementals"
}
},
"description": "Top-level overview totals (dimension=overview only)",
"additionalProperties": false
},
"dimension": {
"type": "string",
"description": "Breakdown dimension returned"
},
"truncated": {
"type": "boolean",
"description": "recipient: true when the upstream capped the reachable result set rather than counting it. geography: true when more areas rank below this page."
},
"totalCount": {
"type": "number",
"description": "Total items for paginated dimensions (when available)"
},
"current_page": {
"type": "number",
"description": "Current page (non-overview dimensions)"
},
"applied_query": {
"type": "string",
"description": "Trimmed recipient query sent upstream"
},
"has_next_page": {
"type": "boolean",
"description": "Whether there are more pages"
},
"page_metadata": {
"type": "object",
"required": [
"has_next",
"page",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page"
},
"limit": {
"type": "number",
"description": "Items per page"
},
"total": {
"type": "number",
"description": "Total items"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages"
}
},
"description": "Pagination metadata (non-overview dimensions)",
"additionalProperties": false
},
"spending_type": {
"type": "string",
"description": "Data type returned — award/total for agency; the requested value echoed for cfda and recipient, whose amounts do not vary with it; obligation for geography; spending for overview"
},
"amount_coverage": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"enum": [
"complete",
"partial",
"unavailable",
"unknown"
],
"type": "string",
"description": "Coverage of requested DEF codes by monetary fields, not provider record completeness"
},
"supported_def_codes": {
"type": "array",
"items": {
"type": "string",
"description": "DEF code included in amounts"
},
"description": "Requested codes included in amounts; omitted when unknown"
},
"unsupported_def_codes": {
"type": "array",
"items": {
"type": "string",
"description": "DEF code excluded from amounts"
},
"description": "Requested codes excluded from amounts; omitted when unknown"
}
},
"description": "Scope of all monetary fields, including geography amounts/per-capita and totals; independent of row membership and counts",
"additionalProperties": false
},
"applied_def_codes": {
"type": "string",
"description": "DEF codes applied (comma-separated)"
},
"applied_dimension": {
"type": "string",
"description": "Breakdown dimension applied"
},
"truncationCeiling": {
"type": "number",
"description": "geography: the lowest aggregated_amount on this page within amount_coverage — no area on a later page has a higher reported value."
}
},
"additionalProperties": false
}usaspending_disaster_spending annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}usaspending_get_federal_account — Get Federal Account
Advertised read-only
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.
usaspending_get_federal_account input schema
{
"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
}usaspending_get_federal_account output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"account_not_found",
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `account_not_found`: No federal account found for the given account code. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Explains when the selected fiscal year has no financial totals or Treasury Account Symbol components; no alternative year is substituted"
},
"children": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Full Treasury Account Symbol (e.g., 080-2020/2021-0120-000) — the availability-period-scoped component of this federal account, not an account_code accepted by this tool"
},
"name": {
"type": "string",
"description": "Treasury Account Symbol title"
},
"obligated_amount": {
"type": "number",
"description": "Obligated amount in USD for this Treasury Account Symbol"
},
"gross_outlay_amount": {
"type": "number",
"description": "Gross outlay amount in USD for this Treasury Account Symbol"
},
"budgetary_resources_amount": {
"type": "number",
"description": "Budgetary resources in USD for this Treasury Account Symbol"
}
},
"description": "Treasury Account Symbol component with its own financial amounts",
"additionalProperties": false
},
"description": "Treasury Account Symbol (TAS) components that make up this federal account, each with its own obligated, outlay, and budgetary-resource amounts. Omitted when the upstream returns none."
},
"bureau_name": {
"type": "string",
"description": "Bureau name within the agency"
},
"fiscal_year": {
"type": "number",
"description": "Fiscal year of the financial data"
},
"account_title": {
"type": "string",
"description": "Full account title"
},
"agency_identifier": {
"type": "string",
"description": "Agency identifier code"
},
"main_account_code": {
"type": "string",
"description": "Main account code"
},
"parent_agency_name": {
"type": "string",
"description": "Managing parent agency name"
},
"federal_account_code": {
"type": "string",
"description": "Federal account code"
},
"total_obligated_amount": {
"type": "number",
"description": "Total obligated amount in USD"
},
"total_budgetary_resources": {
"type": "number",
"description": "Total budgetary resources in USD"
},
"total_gross_outlay_amount": {
"type": "number",
"description": "Total gross outlay amount in USD"
}
},
"additionalProperties": false
}usaspending_get_federal_account annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_get_federal_account_breakdown — Get Federal Account Breakdown
Advertised read-only
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.
usaspending_get_federal_account_breakdown input schema
{
"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
}usaspending_get_federal_account_breakdown output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"period",
"account_code",
"dimension",
"results",
"page_metadata",
"applied_dimension",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Recovery for an empty page, distinguished from a known zero total; absent when results are present."
},
"period": {
"type": "string",
"description": "FY<year> for a selected year, otherwise all available periods"
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Program activity code or object class code (e.g., \"0001\", \"25.2\")"
},
"name": {
"type": "string",
"description": "Program activity name or object class name"
},
"type": {
"type": "string",
"description": "Program activity code system, returned only for the program_activity dimension: \"PAC/PAN\" (legacy program activity code/name) or \"PARK\" (Program Activity Reporting Key). Both can appear for the same account. Absent for object_class rows."
},
"obligations": {
"type": "number",
"description": "Obligated amount in USD"
}
},
"description": "Breakdown row with code, name, and obligated amount",
"additionalProperties": false
},
"description": "Breakdown rows for the requested dimension"
},
"dimension": {
"type": "string",
"description": "Breakdown dimension returned"
},
"totalCount": {
"type": "number",
"description": "Total number of breakdown rows across all pages (when available)"
},
"fiscal_year": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Fiscal year selected by the caller; omitted for all available periods"
},
"time_period": {
"type": "object",
"required": [
"start_date",
"end_date"
],
"properties": {
"end_date": {
"type": "string",
"description": "Inclusive financial reporting period end date (YYYY-MM-DD)"
},
"start_date": {
"type": "string",
"description": "Inclusive financial reporting period start date (YYYY-MM-DD)"
}
},
"description": "Full fiscal-year range applied to financial reporting periods, not award action dates; omitted for all available periods",
"additionalProperties": false
},
"account_code": {
"type": "string",
"description": "Federal account code queried"
},
"current_page": {
"type": "number",
"description": "Current page returned"
},
"has_next_page": {
"type": "boolean",
"description": "Whether there are more pages of breakdown rows"
},
"page_metadata": {
"type": "object",
"required": [
"page",
"has_next",
"has_previous",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page number"
},
"limit": {
"type": "number",
"description": "Results per page"
},
"total": {
"type": "number",
"description": "Total rows across all pages"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages of results"
},
"has_previous": {
"type": "boolean",
"description": "Whether there are previous pages"
}
},
"description": "Pagination metadata",
"additionalProperties": false
},
"applied_dimension": {
"type": "string",
"description": "Breakdown dimension applied"
}
},
"additionalProperties": false
}usaspending_get_federal_account_breakdown annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}usaspending_search_federal_accounts — Search Federal Accounts
Advertised read-onlyOpen-world
List and keyword-search federal accounts by directory toptier code 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 the input agency_identifier (directory toptier_code, e.g. "097" for DoD or "1601" for Labor); account rows return their account-prefix agency_identifier, e.g. "016" for Labor.
usaspending_search_federal_accounts input schema
{
"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": "Directory toptier_code from usaspending_list_agencies (e.g., \"097\" for Defense, \"1601\" for Labor). This differs from the account-prefix agency_identifier returned in account rows (e.g., \"016\" for Labor)."
}
},
"additionalProperties": false
}usaspending_search_federal_accounts output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"page_metadata",
"page",
"has_next"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"page": {
"type": "number",
"description": "Current page number returned"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"api_unavailable",
"api_timeout"
],
"description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"account_name": {
"type": "string",
"description": "Full federal account title"
},
"account_number": {
"type": "string",
"description": "Federal account code (e.g., \"097-8097\") — pass to usaspending_get_federal_account for full detail"
},
"managing_agency": {
"type": "string",
"description": "Name of the managing agency"
},
"agency_identifier": {
"type": "string",
"description": "Account-prefix agency identifier (e.g., 016 for Labor); distinct from the directory toptier_code used by the input filter"
},
"budgetary_resources": {
"type": "number",
"description": "Total budgetary resources for this account in USD"
},
"managing_agency_acronym": {
"type": "string",
"description": "Acronym of the managing agency (e.g., \"DOD\")"
}
},
"description": "Federal account record with code, name, agency, and budget",
"additionalProperties": false
},
"description": "Matching federal accounts"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages of results"
},
"totalCount": {
"type": "number",
"description": "Total number of matching accounts across all pages (when available)"
},
"fiscal_year": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Effective fiscal year of the budgetary resources, as reported by USAspending; account membership spans all submitted years"
},
"page_metadata": {
"type": "object",
"required": [
"page",
"has_next",
"limit"
],
"properties": {
"page": {
"type": "number",
"description": "Current page number"
},
"count": {
"type": "number",
"description": "Total matching accounts across all pages"
},
"limit": {
"type": "number",
"description": "Results per page"
},
"has_next": {
"type": "boolean",
"description": "Whether there are more pages of results"
}
},
"description": "Pagination metadata",
"additionalProperties": false
}
},
"additionalProperties": false
}usaspending_search_federal_accounts annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}Prompts
0 advertised
Resources
1 advertised
usaspending-guide
Use with usaspending_* tools to trace federal awards through recipients and funding accounts, compare spending across reporting periods, or investigate emergency funding without mixing award totals, transaction obligations, and budget data.
usaspending-guide URI
skill://usaspending-guide/SKILL.mdio.modelcontextprotocol/skills
io.modelcontextprotocol/skills URI template
skill://{+path}90-day uptime
A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.
- 2026-11-07: 2 of 2 checks answered
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 719 ms
- 95th percentile latency
- 719 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 719 ms · metadata changed · 18 tool(s), 1 resource(s), 1 resource template(s), 0 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http usaspending-mcp-server-caseyjhand https://usaspending.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add usaspending-mcp-server-caseyjhand --url https://usaspending.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"usaspending-mcp-server-caseyjhand": {
"url": "https://usaspending.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"usaspending-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://usaspending.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"usaspending-mcp-server-caseyjhand": {
"type": "http",
"url": "https://usaspending.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http usaspending-mcp-server-caseyjhand https://usaspending.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
https://usaspending.caseyjhand.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"usaspending-mcp-server-caseyjhand": {
"serverUrl": "https://usaspending.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like usaspending-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.