Search Download

POST/api/v2/download/search/

Powers Custom award and account data on usaspending.gov How the Download Center works

This endpoint is used to search for awards and transactions in the same file.

This route sends a request to the backend to begin generating a zipfile of award data in CSV form for download.

Request

curl -X POST 'https://api.usaspending.gov/api/v2/download/search/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "agencies": [
      {
        "type": "awarding",
        "tier": "toptier",
        "name": "Department of Agriculture"
      }
    ],
    "keywords": [
      "Defense"
    ]
  },
  "columns": [
    "assistance_award_unique_key",
    "assistance_transaction_unique_key",
    "award_id_fain",
    "award_id_uri",
    "modification_number",
    "sai_number",
    "total_funding_amount"
  ],
  "spending_level": [
    "awards",
    "transactions",
    "subawards"
  ]
}'

Request body

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

columnsarray of string
filtersobject · FiltersRequired26 fields
- agenciesarray of Agency4 fields
  - namestringRequired
  - tierenum (string)Required
    Allowed values
    toptier
    subtier
  - typeenum (string)Required
    Allowed values
    funding
    awarding
  - toptier_namestring
    Provided when the name belongs to a subtier agency
- award_amountsarray of AwardAmount2 fields
  - lower_boundnumber
  - upper_boundnumber
- 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.
- award_type_codesarray of string
- contract_pricing_type_codesarray of string
- def_codesarray of DEFC
  List of Disaster Emergency Fund (DEF) Codes (DEFC) defined by legislation at the time of writing. A list of current DEFC can be found here.
- extent_competed_type_codesarray of string
- federal_account_idsarray of string
- keywordsarray of string
- legal_entitiesarray of string
- naics_codesobject · NAICSCodeObject2 fields
  - requirearray of string
    Example ["33"]
  - excludearray of string
    Example ["3333"]
- object_class_idsarray of string
- place_of_performance_locationsarray of Location7 fields
  - countrystringRequired
  - statestring
  - countystring
  - citystring
  - district_originalstring
    A 2 character code indicating the congressional district
    
    When provided, a state must always be provided as well.
    
    When provided, a county must never be provided.
    
    When provided, country must always be "USA".
    
    When provided, district_current must never be provided.
  - district_currentstring
    A 2 character code indicating the current congressional district
    
    When provided, a state must always be provided as well.
    
    When provided, a county must never be provided.
    
    When provided, country must always be "USA".
    
    When provided, district_original must never be provided.
  - zipstring
- place_of_performance_scopestring
- program_activity_idsarray of string
- program_numbersarray of string
- psc_codesenum (PSCCodeObject)
  Supports new PSCCodeObject or legacy array of codes.
- recipient_locationsarray of Location7 fields
  - countrystringRequired
  - statestring
  - countystring
  - citystring
  - district_originalstring
    A 2 character code indicating the congressional district
    
    When provided, a state must always be provided as well.
    
    When provided, a county must never be provided.
    
    When provided, country must always be "USA".
    
    When provided, district_current must never be provided.
  - district_currentstring
    A 2 character code indicating the current congressional district
    
    When provided, a state must always be provided as well.
    
    When provided, a county must never be provided.
    
    When provided, country must always be "USA".
    
    When provided, district_original must never be provided.
  - zipstring
- recipient_scopestring
- recipient_search_textstring
- set_aside_type_codesarray of string
- recipient_type_namesarray of string
- tas_codesarray of TASCodeObject2 fields
  - requirearray of string
    Example ["[`091`]"]
  - excludearray of string
    Example ["[[`091`","`091-0800`]]"]
- time_periodarray of TimePeriod
  While accepting the same format, time period filters are interpreted slightly differently between awards, transactions, and subawards.
- transaction_keyword_searchstring
  Filter awards by keywords in the award's transactions.
- 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
file_formatenum (string)
The format of the file(s) in the zip file containing the data.
Allowed values
- csv
- tsv
- pstxt
Default csv
limitnumber
spending_levelarray of string
Default [`awards`
Example ["subawards","transactions","awards"]

Try it

Runs against the live API. Responses are real data.

POST/api/v2/download/search/

Request body

Response · 200

status_urlstringRequired
The endpoint used to get the status of a download.
file_namestringRequired
Is the name of the zipfile containing CSVs that will be generated (PrimeAwardsTransactionsAndSubawards followed by a timestamp).
file_urlstringRequired
The URL for the file.
download_requestobjectRequired
The JSON object used when processing the download.

Example response

{
  "status_url": "http://localhost:8000/api/v2/download/status?file_name=PrimeAwardsTransactionsAndSubawards_2020-01-13_H21M05S48397603.zip",
  "file_name": "PrimeAwardsTransactionsAndSubawards_2020-01-13_H21M05S48397603.zip",
  "file_url": "/csv_downloads/PrimeAwardsTransactionsAndSubawards_2020-01-13_H21M05S48397603.zip",
  "download_request": {
    "columns": [
      "assistance_award_unique_key",
      "assistance_transaction_unique_key",
      "award_id_fain",
      "award_id_uri",
      "modification_number",
      "sai_number",
      "total_funding_amount"
    ],
    "download_types": [
      "elasticsearch_awards",
      "elasticsearch_transactions",
      "elasticsearch_sub_awards"
    ],
    "file_format": "csv",
    "filters": {
      "agencies": [
        {
          "type": "awarding",
          "tier": "toptier",
          "name": "Department of Agriculture"
        }
      ],
      "keywords": [
        "Defense"
      ]
    },
    "limit": 0,
    "request_type": "search"
  }
}

Recent changes

April 28, 2026Mentioned in the April 28, 2026 release notes
April 17, 2026Reformatted search download time period block
April 17, 2026Updated search timeperiods description
April 16, 2026DEV-14890: Fixed Syntax Error in Filters Fields in API Contract
April 16, 2026DEV-14890: Expanded Filters Fields in API Contract

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