Number of awards for each type

Request

curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_award_count/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "keywords": [
      "Filter is required"
    ]
  }
}'

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_codesarray

    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.

  • object_classesarray of string

    A filter option that supports filtering by object class codes (not names). Only for 'awards'

  • def_codesarray of DEFC

    If the def_codes provided are in the COVID-19 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 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.

• spending_levelenum (string)

  Group the spending by level. This also determines what data source is used for the totals.

  Allowed values

  • awards
  • subawards

  Default awards

• subawardsboolean

  True when you want to group by Subawards instead of Awards. Defaulted to False unless spending_level is set to subawards, then the default is True.

  Example false

Response · 200

• resultsobject · AwardTypeResult6 fields

  • grantsnumberRequired
  • loansnumberRequired
  • contractsnumberRequired
  • direct_paymentsnumberRequired
  • othernumberRequired
  • idvsnumberRequired
• spending_levelenum (string)Required

  Spending level value that was provided in the request.

  Allowed values

  • awards
  • subawards
• messagesarray of string

  An array of warnings or instructional directives to aid consumers of this endpoint with development and debugging.

{
  "results": {
    "grants": 0,
    "loans": 0,
    "contracts": 0,
    "direct_payments": 0,
    "other": 0,
    "idvs": 0
  },
  "spending_level": "awards",
  "messages": []
}

Recent changes

• June 2, 2026DEV-15071: Add-object-classes-initial
• 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 28, 2025DEV-12349: Add spending_level to the response
• March 27, 2025DEV-12349: Add spending_level filter

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