USAspending.gov Getting Started: Accessing Federal Spending Data (2026)

Getting started overview

USAspending.gov provides public access to federal spending data, offering transparency into how the U.S. government allocates funds. The platform's API allows developers and researchers to programmatically access detailed information on contracts, grants, loans, and other financial assistance. Understanding the structure of federal financial reporting is key to effectively utilizing the data, as the API reflects the complexities of government accounting practices.

To begin, users typically identify the specific data endpoints relevant to their research, such as those for award data or account information. The API is designed for direct consumption, meaning no prior registration or API key generation is necessary to make requests. This streamlines the process for those looking to integrate federal spending data into applications or analyses. The official USAspending.gov data sources documentation offers a comprehensive overview of the available data sets and their origins.

This guide outlines the essential steps to make your first successful API call and provides insights into common considerations when working with federal spending data. It covers how to structure requests, interpret responses, and navigate the available documentation to find specific data points.

Quick Reference Guide

Create an account and get keys

Unlike many commercial APIs, USAspending.gov does not require users to create an account or obtain API keys to access its data. All data available through the API is publicly accessible without authentication. This design choice aligns with the government's commitment to transparency and open data initiatives, removing barriers for developers, researchers, and the public to utilize federal spending information.

This means you can proceed directly to formulating your API requests without any preliminary setup involving registration or credential management. The absence of authentication simplifies the integration process, as there's no need to handle API key rotation, secret management, or OAuth flows. This direct access model is common in government open data platforms, enabling immediate data retrieval. For example, similar approaches are adopted in other public data initiatives that prioritize broad access, such as those discussed by the W3C Data on the Web Best Practices which advocates for accessible government data.

While the direct access simplifies initial steps, it's important to be mindful of potential rate limits or fair use policies that may be implicitly enforced to ensure service availability for all users. Although not explicitly documented as strict rate limits for authenticated users, making an excessive number of requests in a short period could, in theory, lead to temporary IP blocking, though this is rare given the API's public nature. It is always advisable to design applications that fetch data efficiently and cache responses when appropriate, reducing the load on the API server.

Your first request

To make your first request to the USAspending.gov API, you will construct an HTTP GET or POST request to one of the available endpoints. A common starting point is querying award data. Let's use the /api/v2/references/toptier_agencies/ endpoint to retrieve a list of top-tier agencies or the /api/v2/references/toptier_agencies/ endpoint to retrieve a subset of agencies for filtering.

Example: Fetching Toptier Agencies

This endpoint provides a list of federal agencies classified as 'top-tier' within the USAspending.gov data structure. It's a useful starting point to understand how the API returns data and to identify agencies you might want to filter for in subsequent, more complex queries.

Request Method: GET

Endpoint: https://api.usaspending.gov/api/v2/references/toptier_agencies/

You can execute this request using a command-line tool like cURL:

curl -X GET "https://api.usaspending.gov/api/v2/references/toptier_agencies/"

Alternatively, in a web browser, simply navigate to: https://api.usaspending.gov/api/v2/references/toptier_agencies/. The browser will display the JSON response directly.

Example: Filtering Award Data (POST Request)

Many of USAspending.gov's more detailed endpoints, particularly those involving filtering or pagination, require a POST request with a JSON body. Let's make a request to find specific awards.

Request Method: POST

Endpoint: https://api.usaspending.gov/api/v2/references/toptier_agencies/

Request Body (JSON):

{
  "filters": {
    "time_period": [
      {
        "start_date": "2023-10-01",
        "end_date": "2024-09-30"
      }
    ],
    "agencies": [
      {
        "type": "awarding",
        "tier": "toptier",
        "name": "Department of Defense"
      }
    ]
  },
  "fields": [
    "award_id",
    "recipient_name",
    "award_amount"
  ],
  "limit": 10,
  "page": 1
}

Using cURL for a POST request:

curl -X POST \
  "https://api.usaspending.gov/api/v2/references/toptier_agencies/" \
  -H "Content-Type: application/json" \
  -d '{ "filters": {"time_period": [{"start_date": "2023-10-01", "end_date": "2024-09-30"}], "agencies": [{"type": "awarding", "tier": "toptier", "name": "Department of Defense"}]}, "fields": ["award_id", "recipient_name", "award_amount"], "limit": 10, "page": 1 }'

This request attempts to fetch the first 10 awards from the Department of Defense within the specified fiscal year, returning only the award ID, recipient name, and award amount. The actual endpoint for filtering awards is typically something like /api/v2/references/toptier_agencies/, which demonstrates the structured query capabilities of the API. Consult the USAspending.gov API documentation for the precise endpoint to query awards with filters.

Common next steps

After successfully making your first request, several common next steps can enhance your use of the USAspending.gov API:

1. Explore More Endpoints: The API offers numerous endpoints beyond basic award data, including detailed information on federal accounts, definitions, and specific transaction types. Review the full list of available endpoints to identify data relevant to your project. Each endpoint is documented with its parameters and expected response structure.
2. Implement Pagination: For queries that return large datasets, implement pagination to retrieve results in manageable chunks. Most list-based endpoints support limit and page parameters, or similar mechanisms, to navigate through results effectively. Properly handling pagination is crucial for efficient data retrieval and avoiding potential resource exhaustion.
3. Understand Data Dictionaries: Federal spending data can be complex due to specific government terminology and reporting standards. The USAspending.gov documentation includes data dictionaries that explain the meaning of various fields and their possible values. Familiarizing yourself with these dictionaries will help you accurately interpret the retrieved data.
4. Programmatic Access with Libraries: For more robust applications, consider using an HTTP client library in your preferred programming language (e.g., Python's requests, JavaScript's fetch, or Java's HttpClient). These libraries simplify handling requests, parsing JSON responses, and managing potential errors. For instance, MDN Web Docs on using Fetch provides a good starting point for web-based clients.
5. Error Handling: Implement error handling in your code to gracefully manage situations such as network issues, malformed requests, or API-specific errors. The API will typically return standard HTTP status codes (e.g., 400 for bad request, 500 for server errors) along with a JSON body detailing the error.
6. Data Storage and Analysis: Decide how you will store and analyze the retrieved data. For large datasets, consider using a database. For less extensive analysis, tools like spreadsheets or data visualization libraries can be effective. Consider the volume and type of data you expect to retrieve when planning your storage and analysis strategy.

Troubleshooting the first call

When making your initial calls to the USAspending.gov API, you might encounter issues. Here are common problems and their solutions:

• Incorrect Endpoint URL: Double-check the URL against the official API documentation. A common mistake is a typo, missing a trailing slash, or using an incorrect version number.

• Missing or Malformed Request Body (for POST requests): For endpoints requiring POST requests, ensure your JSON request body is correctly formatted and contains all mandatory fields. Utilize a JSON linter or validator to verify syntax. Error messages from the API often indicate which fields are missing or malformed.

• HTTP Status Code 400 (Bad Request): This usually indicates an issue with your request's parameters or structure. Review the API documentation for the specific endpoint you are calling to confirm parameter names, types, and allowed values. For instance, date formats must adhere to ISO 8601 (YYYY-MM-DD).

• HTTP Status Code 404 (Not Found): This means the server could not find the requested resource. This nearly always points to an incorrect endpoint URL. Ensure there are no typos and that the path matches the documentation precisely.

• HTTP Status Code 500 (Internal Server Error): This indicates a problem on the API server's side. While rare, if you encounter this, verify your request is valid first. If it is, the issue might be temporary. Waiting a short period and retrying the request often resolves it. If persistent, check the USAspending.gov website for any service announcements or contact their support.

• Network Connectivity Issues: Ensure your internet connection is stable. Basic network troubleshooting steps, like pinging api.usaspending.gov, can help diagnose connectivity problems.

• Empty or Unexpected Data in Response: If your request returns an empty array or data that doesn't match your expectations, review your filters. It's possible your filters are too restrictive or are targeting data that doesn't exist for the specified criteria. Try broadening your filters initially to confirm data availability before narrowing them down.

• JSON Parsing Errors: Ensure your client-side code correctly parses the JSON response. Most programming languages have robust JSON libraries that can handle this. Invalid JSON can occur if the API returns an error page in HTML instead of JSON (e.g., during maintenance).