Skip to content

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; key is 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);