Spending By Subaward Grouped

POST/api/v2/search/spending_by_subaward_grouped/

Powers Advanced Search on usaspending.gov How Advanced Search works

This endpoint takes award filters and returns a list containing filtered award ids, the number of subawards in each award, the total amount of obligations of all the subawards, the prime award obligation, the ratio of subaward to the prime award obligation, and the award unique id.

Request

curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_subaward_grouped/' \
  -H 'Content-Type: application/json' \
  -d '{
  "limit": 10,
  "page": 1,
  "filters": {
    "award_type_codes": [
      "A",
      "B",
      "C"
    ],
    "time_period": [
      {
        "start_date": "2018-10-01",
        "end_date": "2019-09-30"
      }
    ]
  },
  "sort": "award_id",
  "order": "desc"
}'

Request body

The filters object is shared by every search endpoint. The filter object explains each filter with examples.

filtersobject · AdvancedFilterObjectRequired26 fields
- keywordsarray of string
  Example ["transport"]
- descriptionstring
- time_periodarray of TimePeriodObject
  This TimePeriodObject can fall into different categories based on the request.
  - if subawards true
    
    See the Subaward Search category defined in SubawardSearchTimePeriodObject
  - otherwise
    
    See the Award Search category defined in AwardSearchTimePeriodObject
- place_of_performance_scopeenum (string)
  Allowed values
  - domestic
  - foreign
- place_of_performance_locationsarray of LocationObject
  These fields are defined in the StandardLocationObject
- agenciesarray of AgencyObject4 fields
  - typeenum (string)Required
    Allowed values
    awarding
    funding
  - tierenum (string)Required
    Allowed values
    toptier
    subtier
  - namestringRequired
    Example Office of Inspector General
  - toptier_namestring
    Only applicable when tier is subtier. Ignored when tier is toptier. Provides a means by which to scope subtiers with common names to a specific toptier. For example, several agencies have an "Office of Inspector General". If not provided, subtiers may span more than one toptier.
    Example Department of the Treasury
- recipient_search_textarray of string
  Example ["[`Hampton`","`Roads`]",["Text searched across a recipient’s name","UEI","and DUNS"]]
- recipient_scopeenum (string)
  Allowed values
  - domestic
  - foreign
- recipient_locationsarray of LocationObject
  These fields are defined in the StandardLocationObject
- recipient_type_namesarray of string
  Example ["[`category_business`","`sole_proprietorship`]"]
- award_type_codesarrayRequired
  List of filterable award types
  Default 02
- award_idsarray of string
  Award IDs surrounded by double quotes (e.g. "SPE30018FLJFN") will perform exact matches as opposed to the default, fuzzier full text matches. Useful for Award IDs that contain spaces or other word delimiters.
  Example ["[`SPE30018FLGFZ`","`SPE30018FLJFN`]"]
- award_amountsarray of AwardAmounts2 fields
  - lower_boundnumber
  - upper_boundnumber
    Example 1000000
- program_numbersarray of string
  Example ["10.331"]
- naics_codesobject · NAICSCodeObject2 fields
  - requirearray of string
    Example ["33"]
  - excludearray of string
    Example ["3333"]
- tas_codesarray of TASCodeObject2 fields
  - requirearray of string
    Example ["[`091`]"]
  - excludearray of string
    Example ["[[`091`","`091-0800`]]"]
- psc_codesenum (PSCCodeObject)
  Supports new PSCCodeObject or legacy array of codes.
- contract_pricing_type_codesarray of string
  Example ["J"]
- set_aside_type_codesarray of string
  Example ["NONE"]
- extent_competed_type_codesarray of string
  Example ["A"]
- treasury_account_componentsarray of TreasuryAccountComponentsObject7 fields
  - atastringNullable
    Allocation Transfer Agency Identifier - three characters
  - aidstringRequired
    Agency Identifier - three characters
  - bpoastringNullable
    Beginning Period of Availability - four digits
  - epoastringNullable
    Ending Period of Availability - four digits
  - astringNullable
    Availability Type Code - X or null
  - mainstringRequired
    Main Account Code - four digits
  - substringNullable
    Sub-Account Code - three digits
- object_classarray of string
- program_activityarray of number
- program_activitiesarray of ProgramActivityObject
  A filter option that supports filtering by a program activity name or code. Please note that if this filter is used at least one of the members of the object, ProgramActivityObject, need to be provided.
- def_codesarray of DEFC
  If the def_codes provided are in the COVID-19 or IIJA group and the subaward flag is set to False, the query will only return prime awards that have at least one File C record with the supplied DEFC and also have non-zero COVID-19 or IIJA related obligations or outlays. If the def_codes provided are in the COVID-19 or IIJA group and the subaward parameter is set to True, the query will only return results that have a sub_action_date on or after the enactment date of the public law associated with that disaster code.
  - Example: Providing the Z DEF code and setting the subaward parameter to True will only return results where the sub_action_date is on or after 11/15/2021 since this is the enactment date of the public law associated with disaster code Z.
- award_unique_idstring
limitnumber
How many results are returned
pagenumber
The page number that is currently returned.
sortenum (string)
The field on which to order results in the response.
Allowed values
- Any field within the result can be sort
- award_generated_internal_id
- award_id
- award_obligation
- subaward_count
- subaward_obligation
- subaward_to_award_ratio
Default award_id
orderenum (string)
Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order.
Allowed values
- asc
- desc
Default desc

Try it

Runs against the live API. Responses are real data.

POST/api/v2/search/spending_by_subaward_grouped/

Request body

Response · 200

limitnumberRequired
resultsarray of SpendingBySubawardGroupedResultRequired
page_metadataobject · PageMetaDataObject5 fields
- pagenumberRequired
  Example 1
- hasNextbooleanRequired
  Example false
- hasPreviousbooleanRequired
  Example false
- nextnumberRequiredNullable
- previousnumberRequiredNullable
messagesarray of string
An array of warnings or instructional directives to aid consumers of this endpoint with development and debugging.

Example response

{
  "limit": 10,
  "results": [
    {
      "award_id": "0007",
      "subaward_count": 23,
      "award_generated_internal_id": "CONT_AWD_0007_9700_W31P4Q09A0021_9700",
      "subaward_obligation": 6942858.2,
      "award_obligation": 10000000,
      "subaward_to_award_ratio": 0.69428582
    },
    {
      "award_id": "1333LB19F00000306",
      "subaward_count": 6,
      "award_generated_internal_id": "CONT_AWD_1333LB19F00000306_1323_GS35F110DA_4732",
      "subaward_obligation": 1158693,
      "award_obligation": 2500000,
      "subaward_to_award_ratio": 0.4634772
    },
    {
      "award_id": "91003119F0003",
      "subaward_count": 50,
      "award_generated_internal_id": "CONT_AWD_91003119F0003_9100_HHSN316201200002W_7529",
      "subaward_obligation": 16349055,
      "award_obligation": 20000000,
      "subaward_to_award_ratio": 0.81745275
    },
    {
      "award_id": "FA852818F0030",
      "subaward_count": 5,
      "award_generated_internal_id": "CONT_AWD_FA852818F0030_9700_FA852816D0009_9700",
      "subaward_obligation": 482721,
      "award_obligation": 1000000,
      "subaward_to_award_ratio": 0.482721
    },
    {
      "award_id": "FA865118F1016",
      "subaward_count": 3,
      "award_generated_internal_id": "CONT_AWD_FA865118F1016_9700_FA865116D0314_9700",
      "subaward_obligation": 258711.38,
      "award_obligation": 500000,
      "subaward_to_award_ratio": 0.51742276
    },
    {
      "award_id": "HSHQDC17J00370",
      "subaward_count": 47,
      "award_generated_internal_id": "CONT_AWD_HSHQDC17J00370_7001_HSHQDC14DE2035_7001",
      "subaward_obligation": 25170243.97,
      "award_obligation": 30000000,
      "subaward_to_award_ratio": 0.83900813
    },
    {
      "award_id": "N0042118F0167",
      "subaward_count": 16,
      "award_generated_internal_id": "CONT_AWD_N0042118F0167_9700_N0042116D0013_9700",
      "subaward_obligation": 3587182.87,
      "award_obligation": 5000000,
      "subaward_to_award_ratio": 0.71743657
    },
    {
      "award_id": "N4008518F7138",
      "subaward_count": 4,
      "award_generated_internal_id": "CONT_AWD_N4008518F7138_9700_N4008514D7744_9700",
      "subaward_obligation": 338369,
      "award_obligation": 750000,
      "subaward_to_award_ratio": 0.45115867
    },
    {
      "award_id": "N6247318F4138",
      "subaward_count": 311,
      "award_generated_internal_id": "CONT_AWD_N6247318F4138_9700_N6247316D1884_9700",
      "subaward_obligation": 134815478.55,
      "award_obligation": 200000000,
      "subaward_to_award_ratio": 0.67407739
    },
    {
      "award_id": "N6247319F4131",
      "subaward_count": 4,
      "award_generated_internal_id": "CONT_AWD_N6247319F4131_9700_N6247316D2411_9700",
      "subaward_obligation": 541913,
      "award_obligation": 1000000,
      "subaward_to_award_ratio": 0.541913
    }
  ],
  "page_metadata": {
    "page": 1,
    "hasNext": false
  },
  "messages": [
    "For searches, time period start and end dates are currently limited to an earliest date of 2007-10-01.  For data going back to 2000-10-01, use either the Custom Award Download feature on the website or one of our download or bulk_download API endpoints as listed on https://api.usaspending.gov/docs/endpoints. "
  ]
}

Recent changes

September 9, 2026DEV-16050: Initial
August 19, 2025Mentioned in the August 19, 2025 release notes
April 24, 2025DEV-10281: Add object_class back for unmentioned contracts in slack thread
April 24, 2025DEV-10821: Remove object_class from search endpoint api contracts
March 25, 2025Mentioned in the March 25, 2025 release notes

Contract notes

The contract refers to PageMetadataObject but defines it as PageMetaDataObject. The docs read them as the same type.
The contract refers to SpendingBySubawardGroupedResult but never defines it, so its fields aren't listed here.
The contract doesn't state its URL. This path comes from the contract's location in the repo, which mirrors the URL by convention, and matches how usaspending.gov calls it.

Generated from contracts/v2/search/spending_by_subaward_grouped.md in the USAspending API repo.