Subgrants¶
Subgrants (subawards reported under federal grants and cooperative agreements) are exposed at /api/assistance/subgrants/. They are the assistance half of FFATA subaward reporting; the contract half is Subawards. For field definitions, see the Subgrants Data Dictionary.
Endpoints¶
GET /api/assistance/subgrants/(list + filtering + ordering)GET /api/assistance/subgrants/{key}/(detail;keyis the report UUID)
Scoped lists:
GET /api/assistance/grants/{key}/subgrants/, and the same under/loans/,/direct_payments/and/other/(subgrants under a prime assistance award). As on the award's other sub-routes,{key}must name an award on that endpoint: a retired key resolves to the award that carries it now, and a key for an award on another endpoint returns an empty list.GET /api/entities/{uei}/subgrants/(subgrants where the entity is the subgrantee)
Keys¶
A subgrant's key is the subaward report's own identifier: the UUID that SAM.gov assigns to an assistance subaward report (subawardReportNumber) and that USAspending republishes as subaward_sam_report_id, in lowercase. One row per report; an amendment keeps the key and changes the values.
The prime award is reached through award_key, the same assistance_award_unique_key the financial-assistance resources take, and through fain. Almost every subgrant sits under a grant award. prime_assistance_group records which of the four resources held the prime when Tango processed the report, and so where its subgrants are listed:
prime_assistance_group | The prime's subgrants |
|---|---|
grant | /api/assistance/grants/{award_key}/subgrants/ |
loan | /api/assistance/loans/{award_key}/subgrants/ |
direct_payment | /api/assistance/direct_payments/{award_key}/subgrants/ |
other | /api/assistance/other/{award_key}/subgrants/ |
An award moves to another endpoint when its latest action changes assistance type, so the value can lag. If the list under the named endpoint comes back empty, the prime's subgrants are under the endpoint whose detail route answers for award_key; ?award_key= on /api/assistance/subgrants/ finds them wherever the prime is.
Default response¶
All subgrant responses use the shaping pipeline by default. No ?shape= parameter is required to get a shaped response.
Default fields (equivalent to requesting):
amount_suspect,assistance_listings,award_key,awarding_office(*),fain,fsrs_details(*),
funding_office(*),key,place_of_performance(*),place_of_performance_id,
prime_assistance_group,prime_recipient(uei,display_name),prime_recipient_id,recipient_id,
recipient_parent_id,retired_at,subgrant_details(*),subgrant_recipient(uei,display_name)
Shaping¶
Use ?shape= to request a custom field set. Subgrants support the following leaves and expansions.
Leaves¶
| Field | Description |
|---|---|
key | The report UUID |
award_key | Prime award identifier, the same convention the financial-assistance resources use |
fain | Prime award FAIN |
assistance_listings | The prime award's assistance listings as reported, e.g. 12.300: BASIC AND APPLIED SCIENTIFIC RESEARCH; several are ;-separated |
prime_assistance_group | Which financial-assistance resource held the prime award when Tango processed the report: grant, loan, direct_payment or other; null when the prime was not in Tango. See Keys for the list each value leads to |
prime_awardee_uei | Prime recipient UEI |
prime_recipient_id | The prime recipient's entity id, the uuid of /api/entities/ |
recipient_uei | Subgrantee UEI |
recipient_id | The subgrantee's entity id |
recipient_parent_uei | Subgrantee parent UEI |
recipient_parent_id | The subgrantee parent's entity id |
place_of_performance_id | The place-of-performance id, in the financial-assistance place dimension |
pop_cd_original | Place-of-performance congressional district as reported |
pop_cd_current | Place-of-performance congressional district under current boundaries |
amount_suspect | true when the reported amount is not plausibly a subgrant; see the data dictionary |
retired_at | When the report stopped being published, null while it is live; see Retired reports |
usaspending_permalink | The prime award's page on USAspending.gov |
Expansions¶
| Expansion | Fields |
|---|---|
subgrant_details(*) | description, type (always sub-grant), number, amount, action_date, fiscal_year |
fsrs_details(*) | last_modified_date (a timestamp), id (the report UUID, same as key), year, month |
place_of_performance(*) | city, state (the two-letter code), zip, country_code, from the assistance place record |
highly_compensated_officers(*) | name, amount: always five entries; one the report leaves empty has null for both |
prime_recipient(uei,display_name) | Prime recipient identity, resolved against the Entities resource |
subgrant_recipient(uei,display_name,duns) | Subgrantee identity, resolved against the Entities resource; a subgrantee that is not a registered entity returns its uei with display_name: null. duns is always null |
awarding_office(*) | office_code, office_name, agency_code, agency_name, department_code, department_name, from the prime award |
funding_office(*) | Same fields as awarding_office |
Recipient and place details are not stored on the subgrant itself: they come from the entity and place records the ids point at.
Examples¶
# Default response (no shape needed)
/api/assistance/subgrants/
# Minimal fields
/api/assistance/subgrants/?shape=key,fain,award_key,prime_assistance_group
# Subgrant details with recipient info
/api/assistance/subgrants/?shape=key,fain,subgrant_details(*),subgrant_recipient(uei,display_name)
# The program and the awarding office
/api/assistance/subgrants/?shape=key,assistance_listings,awarding_office(office_code,agency_name)
# Highly compensated officers
/api/assistance/subgrants/?shape=key,highly_compensated_officers(name,amount)
# Discover available fields
/api/assistance/subgrants/?show_shapes=true
Filtering¶
| Param | What it does |
|---|---|
key | One or more report UUIDs, pipe-separated (key=a|b). A UUID that names no report matches nothing; a value that is not a UUID returns 400. |
award_key | Filter by prime award key (exact). |
fain | Filter by the prime award's FAIN (case-insensitive exact). |
prime_assistance_group | Filter on prime_assistance_group: grant, loan, direct_payment or other, exact and lowercase, pipe-separated for several (prime_assistance_group=grant|loan). |
prime_uei | Filter by prime recipient UEI (exact). |
sub_uei | Filter by subgrantee UEI (exact). |
assistance_listing | Filter by an assistance listing (CFDA) number the prime award carries, e.g. 93.778. It matches anywhere in assistance_listings, case-insensitively, so pass the full number. |
recipient | Search by subgrantee name (best-effort mapping to UEIs). Min 2 characters. |
fiscal_year | Filter by subgrant action-date fiscal year (exact). |
fiscal_year_gte, fiscal_year_lte | Fiscal year range. |
include_retired | true includes retired reports in the list; see below. |
An unrecognized query parameter on these lists, the scoped ones included, returns 400 with a did-you-mean suggestion rather than being silently ignored, so a mistyped filter never returns a full, unfiltered page. ?fian= answers {"error": "Unknown query parameter: 'fian'. Did you mean: 'fian' -> 'fain'?"}.
Retired reports¶
A report that USAspending published and later stopped publishing (and that SAM.gov has not re-filed since) is kept with retired_at set to when Tango first saw it gone, rather than deleted. Lists omit retired reports unless you send include_retired=true; a detail lookup by key always answers.
Ordering¶
Subgrants support ordering= with a strict allowlist; prefix - for descending:
last_modified_date(the report's last modification,fsrs_details.last_modified_date)
Any other value returns 400 naming the allowed one.
Example: GET /api/assistance/subgrants/?ordering=-last_modified_date
Pagination¶
Subgrants use standard page-number pagination:
page(default 1)limit(max 100)
SDK examples¶
See also: Full SDK method reference — tango-python methods · tango-node methods.
import os
from tango import TangoClient
client = TangoClient(api_key=os.environ["TANGO_API_KEY"])
data = client._get(
"/api/assistance/subgrants/",
params={"assistance_listing": "93.778", "ordering": "-last_modified_date", "limit": 10},
)
print("count:", data.get("count"))
import { TangoClient } from "@makegov/tango-node";
const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
const http = (client as any).http;
const data = await http.get("/api/assistance/subgrants/", {
assistance_listing: "93.778",
ordering: "-last_modified_date",
limit: 10,
});
console.log("count:", data.count);