Spending By Transaction

POST/api/v2/search/spending_by_transaction/

Powers Keyword search on usaspending.gov

Returns transaction records which match the provided filters.

Request

curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_transaction/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "keywords": [
      "test"
    ],
    "award_type_codes": [
      "A",
      "B",
      "C",
      "D"
    ]
  },
  "fields": [
    "Award ID",
    "Mod",
    "Recipient Name",
    "Action Date",
    "Transaction Amount",
    "Awarding Agency",
    "Awarding Sub Agency",
    "Award Type"
  ],
  "page": 1,
  "limit": 35,
  "sort": "Transaction Amount",
  "order": "desc"
}'

Request body

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

filtersobject · AdvancedFilterObjectRequired25 fields
Need to provide award_type_codes
- keywordsarray of string
  Example ["lockheed"]
- descriptionstring
- time_periodarray of TimePeriodObject
  Description: Search based on one or more date range using the transaction's action_date field. Dates should be in the following format: YYYY-MM-DD
  
  Example
  text
  { "time_period": [ { "start_date": "2016-10-01", "end_date": "2017-09-30" } ] }
  Request parameter description:
  - start_date: (required) See Time Period
  - end_date: (required) See Time Period
- award_type_codesarrayRequired
  List of filterable award types
  Default 02
- 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_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 transactions that meet two requirements:
  1. The transaction's associated prime award has at least one File C record with one of the supplied DEFCs.
  2. The matching DEFC's associated public law has an enactment date prior to the transaction's action_date.
- award_unique_idstring
fieldsarrayRequired
The field names to include in the response
limitnumber
The number of results to include per page.
Default 10
Example 5
pagenumber
The page of results to return based on limit.
Default 1
Example 1
sortstringRequired
The field on which to order results in the response.
Default Transaction Amount
Example Transaction Amount
orderenum (string)
The direction in which to order results. asc for ascending or desc for descending.
Allowed values
- asc
- desc
Default desc

Try it

Runs against the live API. Responses are real data.

POST/api/v2/search/spending_by_transaction/

Request body

Response · 200

resultsarray of TransactionResponseRequired
page_metadataobject · PageMetaDataObjectRequired5 fields
- pagenumberRequired
  Example 1
- hasNextbooleanRequired
  Example false
- hasPreviousbooleanRequired
  Example false
- nextnumberRequiredNullable
- previousnumberRequiredNullable
limitnumberRequired
Example 10

Example response

{
  "limit": 10,
  "page_metadata": {
    "page": 1,
    "hasPrevious": false,
    "hasNext": true,
    "previous": null,
    "next": 2
  },
  "results": [
    {
      "Awarding Sub Agency": "U.S. Citizenship and Immigration Services",
      "Award ID": "HSSCCG10J00265",
      "Awarding Agency": "Department of Homeland Security",
      "Action Date": "2012-06-20",
      "internal_id": "24261000",
      "Mod": "P00011",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "15639242.36",
      "generated_internal_id": "CONT_AWD_HSSCCG10J00265_7003_HSHQDC06D00026_7001",
      "Award Type": "DELIVERY ORDER"
    },
    {
      "Awarding Sub Agency": "U.S. Citizenship and Immigration Services",
      "Award ID": "HSSCCG10J00265",
      "Awarding Agency": "Department of Homeland Security",
      "Action Date": "2011-06-21",
      "internal_id": "24261000",
      "Mod": "P00008",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "15226100.09",
      "generated_internal_id": "CONT_AWD_HSSCCG10J00265_7003_HSHQDC06D00026_7001",
      "Award Type": "DELIVERY ORDER"
    },
    {
      "Awarding Sub Agency": "Federal Acquisition Service",
      "Award ID": "GSTO405BF0033",
      "Awarding Agency": "General Services Administration",
      "Action Date": "2008-07-17",
      "internal_id": "22509500",
      "Mod": "0",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "12669957.55",
      "generated_internal_id": "CONT_AWD_GSTO405BF0033_4735_GS09K99BHD0010_4735",
      "Award Type": "DO"
    },
    {
      "Awarding Sub Agency": "U.S. Citizenship and Immigration Services",
      "Award ID": "HSSCCG10J00265",
      "Awarding Agency": "Department of Homeland Security",
      "Action Date": "2013-06-25",
      "internal_id": "24261000",
      "Mod": "P00019",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "10497321.20",
      "generated_internal_id": "CONT_AWD_HSSCCG10J00265_7003_HSHQDC06D00026_7001",
      "Award Type": "DELIVERY ORDER"
    },
    {
      "Awarding Sub Agency": "Centers for Medicare and Medicaid Services",
      "Award ID": "HHSM500201600013U",
      "Awarding Agency": "Department of Health and Human Services",
      "Action Date": "2019-08-26",
      "internal_id": "23325500",
      "Mod": "P00006",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "8303064.00",
      "generated_internal_id": "CONT_AWD_HHSM500201600013U_7530_GS00Q09BGD0039_4735",
      "Award Type": "DELIVERY ORDER"
    },
    {
      "Awarding Sub Agency": "Centers for Medicare and Medicaid Services",
      "Award ID": "HHSM500201600013U",
      "Awarding Agency": "Department of Health and Human Services",
      "Action Date": "2018-08-27",
      "internal_id": "23325500",
      "Mod": "P00003",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "7964806.00",
      "generated_internal_id": "CONT_AWD_HHSM500201600013U_7530_GS00Q09BGD0039_4735",
      "Award Type": "DELIVERY ORDER"
    },
    {
      "Awarding Sub Agency": "Defense Finance and Accounting Service",
      "Award ID": "0148",
      "Awarding Agency": "Department of Defense",
      "Action Date": "2008-12-16",
      "internal_id": "2748500",
      "Mod": "9",
      "Recipient Name": "LEIDOS GOVERNMENT SERVICES, INC.",
      "Transaction Amount": "7796098.43",
      "generated_internal_id": "CONT_AWD_0148_9700_MDA22001D0002_9700",
      "Award Type": "DO"
    },
    {
      "Awarding Sub Agency": "U.S. Citizenship and Immigration Services",
      "Award ID": "HSSCCG10J00265",
      "Awarding Agency": "Department of Homeland Security",
      "Action Date": "2010-09-20",
      "internal_id": "24261000",
      "Mod": "0",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "7780154.53",
      "generated_internal_id": "CONT_AWD_HSSCCG10J00265_7003_HSHQDC06D00026_7001",
      "Award Type": "DELIVERY ORDER"
    },
    {
      "Awarding Sub Agency": "Centers for Medicare and Medicaid Services",
      "Award ID": "HHSM500201600013U",
      "Awarding Agency": "Department of Health and Human Services",
      "Action Date": "2018-01-11",
      "internal_id": "23325500",
      "Mod": "P00002",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "6600114.00",
      "generated_internal_id": "CONT_AWD_HHSM500201600013U_7530_GS00Q09BGD0039_4735",
      "Award Type": "DELIVERY ORDER"
    },
    {
      "Awarding Sub Agency": "Centers for Medicare and Medicaid Services",
      "Award ID": "HHSM500201600013U",
      "Awarding Agency": "Department of Health and Human Services",
      "Action Date": "2017-07-06",
      "internal_id": "23325500",
      "Mod": "5",
      "Recipient Name": "LEIDOS, INC.",
      "Transaction Amount": "6339520.00",
      "generated_internal_id": "CONT_AWD_HHSM500201600013U_7530_GS00Q09BGD0039_4735",
      "Award Type": "DELIVERY ORDER"
    }
  ]
}

Recent changes

July 29, 2025Mentioned in the July 29, 2025 release notes
July 15, 2025DEV-12873: Add recipient_id to spending_by_transaction
May 6, 2025Mentioned in the May 06, 2025 release notes
April 24, 2025DEV-10821: Remove object_class from search endpoint api contracts
April 1, 2025DEV-12290: Add unique award id for transaction filter

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