Bulk Award Download

Request

curl -X POST 'https://api.usaspending.gov/api/v2/bulk_download/awards/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "prime_award_types": [
      "A",
      "B",
      "C",
      "D",
      "IDV_A",
      "IDV_B",
      "IDV_B_A",
      "IDV_B_B",
      "IDV_B_C",
      "IDV_C",
      "IDV_D",
      "IDV_E",
      "02",
      "03",
      "04",
      "05",
      "10",
      "06",
      "07",
      "08",
      "09",
      "11",
      "-1"
    ],
    "date_type": "action_date",
    "date_range": {
      "start_date": "2019-10-01",
      "end_date": "2020-09-30"
    },
    "agencies": [
      {
        "type": "funding",
        "tier": "subtier",
        "name": "Animal and Plant Health Inspection Service",
        "toptier_name": "Department of Agriculture"
      }
    ]
  },
  "file_format": "csv"
}'

Request body

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

• filtersobject · FiltersRequired10 fields

  • agenciesarray of AgencyRequired4 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

  • prime_award_typesarray of string

    Example ["IDV_A","IDV_B","IDV_B_A","IDV_B_B","IDV_B_C","IDV_C","IDV_D","IDV_E","02","03","04","05","06","07","08","09","10","11","A","B","C","D","-1","F001","F002","F003","F004","F005","F006","F007","F008","F009","F010"]

  • date_rangeobject · TimePeriodRequired2 fields

    Object with start and end dates

    • start_datestringRequired
    • end_datestringRequired
  • date_typeenum (string)Required
    Allowed values

    • action_date
    • last_modified_date
  • keywordstring
  • 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_scopeenum (string)
    Allowed values

    • domestic
    • foreign
  • 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_scopeenum (string)
    Allowed values

    • domestic
    • foreign
  • sub_award_typesarray of string

    Example ["grant","procurement"]

• columnsarray of string
• file_formatenum (string)

  The format of the file(s) in the zip file containing the data.

  Allowed values

  • csv
  • tsv
  • pstxt

  Default csv

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 (file_name is timestamp followed by _transactions or _awards).

• file_urlstringRequired

  The URL for the file.

• download_requestobjectRequired

  The JSON object used when processing the download.

{
  "status_url": "https://api.usaspending.gov/api/v2/download/status?file_name=All_PrimeTransactions_2020-09-16_H15M20S52934397.zip",
  "file_name": "All_PrimeTransactions_2020-09-16_H15M20S52934397.zip",
  "file_url": "https://files.usaspending.gov/generated_downloads/dev/All_PrimeTransactions_2020-09-16_H15M20S52934397.zip",
  "download_request": {
    "columns": [],
    "download_types": [
      "prime_awards"
    ],
    "file_format": "csv",
    "filters": {
      "agencies": [
        {
          "name": "Animal and Plant Health Inspection Service",
          "tier": "subtier",
          "toptier_name": "Department of Agriculture",
          "type": "funding"
        }
      ],
      "prime_and_sub_award_types": {
        "prime_awards": [
          "02",
          "03",
          "04",
          "05",
          "06",
          "07",
          "08",
          "09",
          "10",
          "11",
          "A",
          "B",
          "C",
          "D",
          "IDV_A",
          "IDV_B",
          "IDV_B_A",
          "IDV_B_B",
          "IDV_B_C",
          "IDV_C",
          "IDV_D",
          "IDV_E",
          "-1"
        ],
        "sub_awards": []
      },
      "time_period": [
        {
          "date_type": "action_date",
          "end_date": "2020-09-30",
          "start_date": "2019-10-01"
        }
      ]
    },
    "request_type": "award"
  }
}

Recent changes

• June 17, 2026DEV-15240: Update API contracts with new Assistance Type codes
• July 19, 2023Mentioned in the July 19, 2023 release notes
• September 21, 2020Mentioned in the September 21, 2020 release notes
• September 8, 2020Mentioned in the September 08, 2020 release notes

Generated from contracts/v2/bulk_download/awards.md in the USAspending API repo.