US federal spending totals by category · USAspending API

GET https://api.api.sh/usaspending/v1/totals

1 credit / call government & registries try it in the playground →

Federal spending totals grouped by awarding or funding agency or sub-agency, recipient, assistance listing, NAICS, PSC, state or territory, country, county, congressional district, federal account or disaster code, for awards matching the filters (default period: the current fiscal year). Pass next_page back as page; null on the last page.

Every response includes credits_used: the credits this call cost.

Parameters

name	type	description
`by`	awarding_agency \| awarding_subagency \| funding_agency \| funding_subagency \| recipient \| cfda \| naics \| psc \| state_territory \| country \| county \| district \| federal_account \| defc	Grouping (default awarding_agency). Example: `recipient`
`type`	contracts \| idvs \| grants \| loans \| direct_payments \| other	Award group (default all).
`q`	string	Keywords, comma list (each 3+ characters).
`recipient`	string	Recipient name, UEI or DUNS, comma list.
`agency`	string	Agency name (e.g. Department of Defense); see /usaspending/v1/agencies.
`agency_tier`	toptier \| subtier	Agency level.
`agency_type`	awarding \| funding	Awarding or funding agency.
`from`	string	Start of the period (YYYY-MM-DD, 2007-10-01 or later). Example: `2025-01-01`
`to`	string	End of the period (YYYY-MM-DD).
`date_type`	action_date \| date_signed \| last_modified_date \| new_awards_only	Which date the period applies to.
`min_amount`	number	Minimum award amount (USD).
`max_amount`	number	Maximum award amount (USD).
`naics`	string	NAICS codes, comma list (2-6 digits). Example: `336411`
`psc`	string	Product and service codes, comma list.
`assistance_listing`	string	Assistance listing (CFDA) numbers, comma list (e.g. 93.778).
`award_id`	string	Award ids (PIID or FAIN), comma list.
`set_aside`	string	Set-aside codes, comma list (e.g. SBA, 8A, WOSB).
`extent_competed`	string	Extent-competed codes, comma list.
`def_codes`	string	Disaster emergency fund codes, comma list.
`place_of_performance`	string	US state code (CA, or CA-037 for a county) or a 3-letter country code.
`recipient_location`	string	Recipient's US state code or 3-letter country code.
`recipient_type`	string	Recipient business types, comma list (e.g. small_business, nonprofit, higher_education).
`limit`	integer	Results per page.
`page`	integer	Page number (1-based). Pass `next_page` back as `page`; null on the last page.

Every endpoint also takes fresh, raw, fields (see lean responses and caching).

Example

curl "https://api.api.sh/usaspending/v1/totals?by=recipient" \
  -H "x-api-key: $APISH_KEY"

import os, requests

res = requests.get(
    "https://api.api.sh/usaspending/v1/totals",
    params={"by": "recipient"},
    headers={"x-api-key": os.environ["APISH_KEY"]},
    timeout=120,
)
res.raise_for_status()
data = res.json()

const url = new URL("https://api.api.sh/usaspending/v1/totals");
url.searchParams.set("by", "recipient");

const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();

Response

A JSON object with the fields described above, plus raw (the source's own data), cached, fetched_at and credits_used. Errors return {"success": false, "error": "…"} with the HTTP status (see errors). A lookup that ran but found nothing (404) costs the price above; refused calls and errors on our side are free (what's charged).

The fastest way to see the full response is the playground: it runs this endpoint with your account and shows the exact JSON.