API Endpoints

This page is intended for users who are already familiar with APIs. If you're not sure what endpoint means, and what GET and POST requests are, you may find the introductory tutorial more useful to start.

Endpoints do not currently require any authorization.

Status Codes

In general, status codes returned are as follows:

  • 200 if the request is successful
  • 400 if the request is malformed
  • 500 for server-side errors

Endpoints and Methods

The currently available endpoints are listed in the following table.

Endpoint Index

Endpoint Methods Description
/api/v2/autocomplete/awarding_agency POST Returns awarding agencies matching the specified search text
/api/v2/autocomplete/cfda POST Returns CFDA programs matching the specified search text
/api/v2/autocomplete/funding_agency POST Returns funding agencies matching the specified search text
/api/v2/autocomplete/naics POST Returns NAICS objects matching the specified search text
/api/v2/autocomplete/psc POST Returns product or service (PSC) codes and their descriptions based on a search string. This may be the 4-character PSC code or a description string.
/api/v2/autocomplete/recipient POST Returns Parent and Recipient DUNS matching the search text in order of similarity. Returns a list of legal entity IDs whose recipient name contains search text, OR a list of legal entity IDs matching a valid DUNS number. Includes search_text in response for frontend.
/api/v2/award_spending/recipient/ POST Returns all award spending by recipient for a given fiscal year and agency id
/api/v2/awards/<AWARD_ID>/ GET Returns details about specific award
/api/v2/awards/idvs/activity/ POST Returns information about child awards and grandchild awards for a given IDV (Indefinite Delivery Vehicle).
/api/v2/awards/idvs/amounts/<AWARD_ID>/ GET Returns the direct children of an IDV
/api/v2/awards/idvs/awards/ POST Returns IDVs or contracts related to the requested Indefinite Delivery Vehicle award (IDV)
/api/v2/awards/idvs/funding/ POST Returns File C funding records associated with an IDV
/api/v2/awards/last_updated GET Returns date of last update
/api/v2/budget_functions/list_budget_functions/ GET Returns all Budget Functions associated with a TAS, ordered by Budget Function code
/api/v2/budget_functions/list_budget_subfunctions/ POST Returns all Budget Functions associated with a TAS, ordered by Budget Function code
/api/v2/bulk_download/awards POST Generates zip file for download of award data in CSV format
/api/v2/bulk_download/list_agencies POST Lists all the agencies and the subagencies or federal accounts associated under specific agencies.
/api/v2/bulk_download/list_monthly_files POST Lists the monthly files associated with the requested params
/api/v2/bulk_download/status GET Returns the current status of a download job that that has been requested with the v2/bulk_download/awards/ or v2/bulk_download/transaction/ endpoint that same day.
/api/v2/download/accounts POST Generates zip file for download of account data in CSV format
/api/v2/download/awards POST Generates zip file for download of award data in CSV format
/api/v2/download/count POST Returns the number of transactions that would be included in a download request for the given filter set
/api/v2/download/status GET gets the current status of a download job that that has been requested with the v2/download/awards/ or v2/download/transaction/ endpoint that same day
/api/v2/download/transactions POST Generates zip file for download of award data in CSV format
/api/v2/federal_accounts/ POST Returns financial spending data by object class
/api/v2/federal_accounts/<ACCOUNT_CODE>/ GET Returns a federal account based on its federal account code
/api/v2/federal_accounts/<ACCOUNT_CODE>/available_object_classes GET Returns financial spending data by object class based on account's internal ID
/api/v2/federal_accounts/<ACCOUNT_CODE>/fiscal_year_snapshot GET Returns budget information for a federal account for the most recent year based on account's internal ID
/api/v2/federal_accounts/<ACCOUNT_CODE>/fiscal_year_snapshot/<YEAR> GET Returns budget information for a federal account for the year provided based on account's internal ID
/api/v2/federal_obligations GET Returns a paginated list of obligations for the provided agency for the provided year
/api/v2/financial_balances/agencies/ GET Returns financial balances by agency and the latest quarter for the given fiscal year
/api/v2/financial_spending/major_object_class/ GET Returns financial spending data by object class for the latest quarter based on the given fiscal year
/api/v2/financial_spending/object_class/ GET Returns financial spending data by object class for the latest quarter based on the given fiscal year
/api/v2/recipient/children/<DUNS>/ GET Returns recipient details based on DUNS number
/api/v2/recipient/duns/ POST Returns a list of recipients in USAspending DB
/api/v2/recipient/duns/<HASH_VALUE>/ GET Returns a high-level overview of a specific recipient, given its id
/api/v2/recipient/state/ GET Returns basic information about the specified state
/api/v2/recipient/state/<FIPS>/ GET Returns basic information about the specified state
/api/v2/recipient/state/awards/<FIPS>/ GET Returns award breakdown based on FIPS
/api/v2/references/agency/<AGENCY_ID>/ GET NO DESCRIPTION
/api/v2/references/data_dictionary/ GET returns a JSON structure of the Schema team's Rosetta Crosswalk Data Dictionary
/api/v2/references/toptier_agencies/ GET Returns all toptier agencies and related, relevant data.
/api/v2/search/new_awards_over_time POST Returns a list of time periods with the new awards in the appropriate period within the provided time range
/api/v2/search/spending_by_award POST Returns the fields of the filtered awards
/api/v2/search/spending_by_award_count POST Returns the number of awards in each award type (Contracts, IDV, Loans, Direct Payments, Grants, and Other)
/api/v2/search/spending_by_category POST Returns data that is grouped in preset units to support the various data visualizations on USAspending.gov's Advanced Search page
/api/v2/search/spending_by_geography POST Returns spending by state code, county code, or congressional district code
/api/v2/search/spending_by_transaction POST Returns awards where a certain subset of fields match against search term
/api/v2/search/spending_by_transaction_count POST Returns awards where a certain subset of fields match against search term
/api/v2/search/spending_over_time POST Returns spending by time
/api/v2/search/transaction_spending_summary POST Returns the number of transactions and the sum of federal action obligations for prime awards given a set of award of filters
/api/v2/spending/ POST Returns spending data information through various types and filters
/api/v2/subawards/ POST Returns subawards either related, optionally, to a specific parent award, or for all parent awards if desired
/api/v2/transactions/ POST Returns transactions related to a specific parent award