GnistAI GnistAI
Log in

USASpending

U.S. federal spending data — contracts, grants, and agency budgets.

Overview   |   MCP   |   REST API   |   OpenAPI   |   CLI   |   Tutorial   |   Toolkits   |   Home
status: healthy status status healthy healthy tools: 6 tools tools 6 6 type: api wrapper type type api wrapper api wrapper lifecycle: maintained lifecycle lifecycle maintained maintained Economics

Data source: USASpending.gov

MCP Endpoint (Streamable HTTP) https://context.gnist.ai/mcp/usaspending/
Authentication

All requests require a Gnist-API-Key header (or api_key query parameter).

Free tier: 100 calls/day. Get your API key.

Tools (6)

search_awards

Search USASpending.gov for federal awards (contracts, grants, loans, direct payments).

USASpending.gov is the official source for US federal government spending data,
covering $6–7 trillion annually from FY2008–present, updated nightly.

Args:
query: Keywords to search for (e.g. "Lockheed Martin", "cybersecurity", "COVID-19 relief").
award_type: Filter by award category. Values: "contracts" (default), "grants", "loans",
"direct_payments".
agency: Filter by awarding agency name (e.g. "Department of Defense",
"Department of Health and Human Services").
date_from: Only include awards starting on or after this date (YYYY-MM-DD).
date_to: Only include awards starting on or before this date (YYYY-MM-DD).
limit: Number of results to return (1–50, default 10). Sorted by award amount descending.

Returns:
Dict with 'count', 'has_next', and 'awards' list. Each award includes award_id,
recipient_name, award_amount, awarding_agency, start/end dates, description,
and NAICS industry classification.

ParameterTypeRequiredDescription
querystringrequiredKeywords to search for (e.g. "Lockheed Martin", "cybersecurity", "COVID-19 relief").
award_typeanyoptionalFilter by award category. Values: "contracts" (default), "grants", "loans", "direct_payments".
agencyanyoptionalFilter by awarding agency name (e.g. "Department of Defense", "Department of Health and Human Services").
date_fromanyoptionalOnly include awards starting on or after this date (YYYY-MM-DD).
date_toanyoptionalOnly include awards starting on or before this date (YYYY-MM-DD).
limitintegeroptionalNumber of results to return (1–50, default 10). Sorted by award amount descending. (default: 10)
JSON-RPC Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_awards",
    "arguments": {
      "query": "example"
    }
  }
}
get_award

Fetch detailed information for a specific federal award.

Use the generated_internal_id from search_awards results (e.g.
"CONT_AWD_N0001917C0001_9700_-NONE-_-NONE-") to look up full details including
recipient info, subaward data, contracting details, and place of performance.

Args:
award_id: The generated_unique_award_id or generated_internal_id from search results.

Returns:
Dict with full award details: obligation amounts, recipient, agencies, NAICS/PSC codes,
subaward count, place of performance, and period of performance dates.

ParameterTypeRequiredDescription
award_idstringrequiredThe generated_unique_award_id or generated_internal_id from search results.
JSON-RPC Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_award",
    "arguments": {
      "award_id": "example"
    }
  }
}
get_recipient

Search for or fetch a federal award recipient (contractor, grantee, etc.).

Search by name/keyword to find recipients, or pass a recipient_id (from search_awards
results) to get a full profile with alternate names, business types, and location.

Args:
keyword: Recipient name or keyword to search (e.g. "Raytheon", "Johns Hopkins").
recipient_id: Specific recipient hash ID for full profile lookup
(e.g. "6cf5fb1b-4988-d087-5dc1-70939d8fc6c4-C").
limit: Number of search results (1–50, default 10). Ignored when using recipient_id.

Returns:
Dict with 'count', 'total', and 'recipients' list. Each includes name, UEI,
total award amount, and (for profile lookups) business types, location, and alternate names.

ParameterTypeRequiredDescription
keywordanyoptionalRecipient name or keyword to search (e.g. "Raytheon", "Johns Hopkins").
recipient_idanyoptionalSpecific recipient hash ID for full profile lookup (e.g. "6cf5fb1b-4988-d087-5dc1-70939d8fc6c4-C").
limitintegeroptionalNumber of search results (1–50, default 10). Ignored when using recipient_id. (default: 10)
JSON-RPC Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_recipient",
    "arguments": {}
  }
}
get_agency_spending

Fetch budgetary resources for a US federal agency.

Common toptier agency codes:
- "097" — Department of Defense
- "075" — Department of Health and Human Services
- "012" — Department of Agriculture
- "069" — Department of Transportation
- "089" — Department of Energy
- "028" — Social Security Administration

Args:
agency_code: Three-digit toptier agency code (e.g. "097" for DoD).
fiscal_year: Federal fiscal year (Oct–Sep). Omit for most recent available.

Returns:
Dict with toptier_code, fiscal_year, agency_budgetary_resources (total budget authority),
agency_total_obligated (committed), agency_total_outlayed (spent),
and total_budgetary_resources (all-government total for comparison).

ParameterTypeRequiredDescription
agency_codestringrequiredThree-digit toptier agency code (e.g. "097" for DoD).
fiscal_yearanyoptionalFederal fiscal year (Oct–Sep). Omit for most recent available.
JSON-RPC Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_agency_spending",
    "arguments": {
      "agency_code": "example"
    }
  }
}
spending_by_geography

Aggregate federal spending by geographic area (state, county, or congressional district).

Useful for analyzing where federal money flows — e.g. which states receive the most
defense contracts, or where COVID relief grants were concentrated.

Args:
keywords: Search terms to filter spending (e.g. ["cybersecurity"], ["COVID-19", "relief"]).
geo_layer: Geographic granularity. Values: "state", "county", "district"
(congressional district). Default "state".
scope: What location to aggregate by. Values: "place_of_performance" (where work happens),
"recipient_location" (where recipient is based). Default "place_of_performance".
award_type: Filter by category: "contracts", "grants", "loans", "direct_payments".
Omit for all types.
date_from: Start date filter (YYYY-MM-DD).
date_to: End date filter (YYYY-MM-DD).

Returns:
Dict with 'scope', 'geo_layer', 'count', and 'results' list. Each result includes
shape_code (state/county/district code), display_name, aggregated_amount, population,
and per_capita spending.

ParameterTypeRequiredDescription
keywordslist[string]requiredSearch terms to filter spending (e.g. ["cybersecurity"], ["COVID-19", "relief"]).
geo_layerstringoptionalGeographic granularity. Values: "state", "county", "district" (congressional district). Default "state". (default: "state")
scopestringoptionalWhat location to aggregate by. Values: "place_of_performance" (where work happens), "recipient_location" (where recipient is based). Default "place_of_performance". (default: "place_of_performance")
award_typeanyoptionalFilter by category: "contracts", "grants", "loans", "direct_payments". Omit for all types.
date_fromanyoptionalStart date filter (YYYY-MM-DD).
date_toanyoptionalEnd date filter (YYYY-MM-DD).
JSON-RPC Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "spending_by_geography",
    "arguments": {
      "keywords": [
        "example"
      ]
    }
  }
}
report_feedback

Report a bug, feature request, or general feedback for this data source.

Use this when something doesn't work as expected, when you'd like
a new feature, or when you have suggestions for improvement.

Args:
feedback: Describe the issue or suggestion.
feedback_type: One of 'bug', 'feature_request', or 'general'.

ParameterTypeRequiredDescription
feedbackstringrequired
feedback_typestringoptional (default: "general")
JSON-RPC Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "report_feedback",
    "arguments": {
      "feedback": "example"
    }
  }
}

Quick Start

Shell 
curl -X POST "https://context.gnist.ai/mcp/usaspending/" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_awards", "arguments": {"query": "example"}}}'
Python 
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/usaspending/",
    headers={"Gnist-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_awards",
    "arguments": {
      "query": "example"
    }
  }
},
)
print(resp.json())

Related Toolkits (Economics)

Economic Indicators
Economic indicators — unified access to World Bank development data, OECD statistics, Eurostat European data, and BLS la
BLS (Bureau of Labor Statistics)
U.S. labor statistics including employment, CPI, wages, and unemployment data.
DST (Statistics Denmark)
Danish official statistics — population, employment, income, housing, trade, and economic data.
ESCO (Skills & Occupations)
European skills, competences, and occupations classification — 13,890 skills and 3,008 occupations linked to ISCO-08 cod

Resources

Toolkit Overview
Landing page with health status and quick start.
Tool Schemas (JSON)
Full input/output JSON schemas for all tools.
Developer Quickstart
Get from zero to your first API call in under two minutes.
Get an API Key
Free tier: 100 calls/day. No credit card required.