Spending Over Time

POST/api/v2/search/spending_over_time/

Powers Advanced Search on usaspending.gov How Advanced Search works How a recipient profile is built

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

This endpoint returns a list of aggregated award amounts grouped by time period in ascending order (earliest to most recent).

Request

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

Request body

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

groupenum (string)Required
Allowed values
- calendar_year
- fiscal_year
- quarter
- month
Default fiscal_year
filtersobject · AdvancedFilterObjectRequired24 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 Transaction Search category defined in TransactionSearchTimePeriodObject
- 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
- 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, the query will only return results of transactions where the action_date is on or after the enactment date of the public law associated with that disaster code.
subawardsboolean
True to group by sub-awards instead of prime awards. Defaults to false.
Default false
spending_levelenum (string)
Group the spending by level. This also determines what data source is used for the totals.
Allowed values
- transactions
- awards
- subawards
Default transactions

Try it

Runs against the live API. Responses are real data.

POST/api/v2/search/spending_over_time/

Request body

Response · 200

groupenum (string)Required
Allowed values
- calendar_year
- fiscal_year
- quarter
- month
spending_levelenum (string)Required
Spending level value that was provided in the request.
Allowed values
- transactions
- awards
- subawards
resultsarray of TimeResult15 fields
- time_periodobject · TimePeriodGroupRequired4 fields
  - calendar_yearstring
    Depending on the grouping, either calendar_year or fiscal_year will always be returned.
  - fiscal_yearstring
  - quarterstring
    Excluded when grouping by fiscal_year or month or calendar_year.
  - monthstring
    Excluded when grouping by fiscal_year or quarter or calendar_year.
- aggregated_amountnumberRequired
  The aggregate award amount for this time period and the given filters.
- Contract_ObligationsnumberRequired
- Loan_ObligationsnumberRequired
- Idv_ObligationsnumberRequired
- Grant_ObligationsnumberRequired
- Direct_ObligationsnumberRequired
- Other_ObligationsnumberRequired
- total_outlaysnumberRequiredNullable
  The aggregate outlay amount for this time period and the given filters.
- Contract_OutlaysnumberRequiredNullable
- Loan_OutlaysnumberRequiredNullable
- Idv_OutlaysnumberRequiredNullable
- Grant_outlaysnumberRequiredNullable
- Direct_OutlaysnumberRequiredNullable
- Other_OutlaysnumberRequiredNullable
messagesarray of string
An array of warnings or instructional directives to aid consumers of this endpoint with development and debugging.

Example response

{
  "group": "calendar_year",
  "spending_level": "transactions",
  "results": [
    {
      "time_period": {},
      "aggregated_amount": 0,
      "Contract_Obligations": 0,
      "Loan_Obligations": 0,
      "Idv_Obligations": 0,
      "Grant_Obligations": 0,
      "Direct_Obligations": 0,
      "Other_Obligations": 0,
      "total_outlays": null,
      "Contract_Outlays": null,
      "Loan_Outlays": null,
      "Idv_Outlays": null,
      "Grant_outlays": null,
      "Direct_Outlays": null,
      "Other_Outlays": null
    }
  ],
  "messages": []
}

Recent changes

September 8, 2025DEV-13063: Update test and api contract
July 8, 2025Mentioned in the July 8, 2025 release notes
May 6, 2025Mentioned in the May 06, 2025 release notes
April 24, 2025DEV-10821: Remove object_class from search endpoint api contracts
January 9, 2025DEV-11551: Update API Contracts

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