USAspending.gov API Reference

The endpoint & request shape

Endpoint

POST https://api.usaspending.gov/api/v2/search/spending_by_award/

No authentication, no API key. Content-Type application/json.

Request body shape

{
  "filters": {
    "time_period": [
      { "start_date": "2026-07-01", "end_date": "2026-08-01" }
    ],
    "award_type_codes": ["A", "B", "C", "D"],
    "agencies": [
      { "type": "awarding", "tier": "toptier", "name": "Department of Defense" }
    ],
    "recipient_search_text": ["Lockheed Martin"],
    "naics_codes": ["541511"],
    "psc_codes": ["D301"],
    "place_of_performance_locations": [
      { "country": "USA", "state": "VA" }
    ]
  },
  "fields": ["Award ID", "Recipient Name", "Award Amount", "Total Outlays"],
  "sort": "Award Amount",
  "order": "desc",
  "page": 1,
  "limit": 100
}

The filters object

The fields array

A list of field names (not raw JSON keys — they're human-readable strings like "Award ID" and "Recipient Name", mixed with a smaller number of snake_case ones like naics_code) that determines what comes back in each result object. See the critical finding below before you build this list from guesswork.

Critical finding: fields is not server-validated

The exact call that proved it

curl -X POST "https://api.usaspending.gov/api/v2/search/spending_by_award/" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "time_period": [{"start_date":"2026-07-01","end_date":"2026-08-01"}],
      "award_type_codes": ["A","B","C","D"]
    },
    "fields": ["Award ID", "Totally Fake Field XYZ"],
    "sort": "Award ID",
    "order": "desc",
    "page": 1,
    "limit": 2
  }'

Real response (trimmed)

{
  "results": [
    {
      "internal_id": 360893879,
      "Award ID": "W912P526FA088",
      "Totally Fake Field XYZ": null,
      "generated_internal_id": "CONT_AWD_W912P526FA088_9700_W912EK22D0006_9700"
    }
  ],
  "page_metadata": { "page": 1, "hasNext": true, ... }
}

How to discover the genuinely valid field set

The fields array isn't validated, but sort is — and its error message is, unintentionally, the authoritative list of every field name the current award-type category actually supports. Send a request with a sort value you know is wrong, and the API's 400/422 response enumerates the real set.

Call that surfaces the contracts field list

curl -X POST "https://api.usaspending.gov/api/v2/search/spending_by_award/" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "time_period": [{"start_date":"2026-07-01","end_date":"2026-08-01"}],
      "award_type_codes": ["A","B","C","D"]
    },
    "fields": ["Award ID"],
    "sort": "Totally Fake Sort Field",
    "order": "desc",
    "page": 1,
    "limit": 2
  }'

Real response — the full valid field list for contracts (award_type_codes A/B/C/D)

{
  "detail": "Sort value 'Totally Fake Sort Field' not found in Contract Award mappings: ['Award ID', 'Recipient Name', 'Recipient DUNS Number', 'recipient_id', 'Awarding Agency', 'Awarding Agency Code', 'Awarding Sub Agency', 'Awarding Sub Agency Code', 'Funding Agency', 'Funding Agency Code', 'Funding Sub Agency', 'Funding Sub Agency Code', 'Place of Performance City Code', 'Place of Performance State Code', 'Place of Performance Country Code', 'Place of Performance Zip5', 'Description', 'Last Modified Date', 'Base Obligation Date', 'prime_award_recipient_id', 'generated_internal_id', 'def_codes', 'COVID-19 Obligations', 'COVID-19 Outlays', 'Infrastructure Obligations', 'Infrastructure Outlays', 'Recipient UEI', 'naics_code', 'naics_description', 'psc_code', 'psc_description', 'cfda_number', 'cfda_program_title', 'sub_cfda_program_titles', 'recipient_location_city_name', 'recipient_location_state_code', 'recipient_location_country_name', 'recipient_location_address_line1', 'recipient_location_address_line2', 'recipient_location_address_line3', 'sub_recipient_location_city_name', 'sub_recipient_location_state_code', 'sub_recipient_location_country_name', 'sub_recipient_location_address_line1', 'pop_city_name', 'pop_state_code', 'pop_country_name', 'sub_pop_city_name', 'sub_pop_state_code', 'sub_pop_country_name', 'Start Date', 'End Date', 'Award Amount', 'Total Outlays', 'Contract Award Type']"
}

The same call against grants (award_type_codes 02/03/04/05) returns a different list

Swap award_type_codes to ["02","03","04","05"] in the same malformed-sort request and the enumerated set changes — it's headed "...not found in Non-Loan Assistance Award mappings:", includes everything contracts has (minus contract-only fields like Contract Award Type), and adds grant-specific fields not present on the contracts list: 'Award Type', 'SAI Number', 'CFDA Number', 'Assistance Listings'.

Critical finding: page_metadata.hasNext is unreliable past ~page 100

The correct stopping condition

Stop paging when a page comes back short of the requested limit (or empty) — not when hasNext says false. A full page (exactly limit rows) means there may be more; a short or empty page is the only reliable end-of-results signal we found.

// Do this:
hasNext = pageResults.length === PAGE_LIMIT;

// Not this:
hasNext = response.page_metadata.hasNext; // lies past ~page 100

This is exactly the fix shipped in open-fedspend-data's fetcher — see its fetchAllAwards() for the real implementation, including the comment documenting the exact page range where the flag failed on a live pull.

Pagination: the 50,000-row cap and the cursor workaround

The cap

Simple page-number pagination (page + limit) is capped at page * limit <= 50,000. Requesting further pages doesn't return empty results — it returns an explicit error telling you exactly what to do instead:

curl -X POST "https://api.usaspending.gov/api/v2/search/spending_by_award/" \
  -H "Content-Type: application/json" \
  -d '{"filters": {...}, "fields": ["Award ID"], "sort": "Award ID", "order": "desc", "page": 501, "limit": 100}'

{
  "detail": "Page #501 with limit 100 is over the maximum result limit 50000. Please provide the 'last_record_sort_value' and 'last_record_unique_id' to paginate sequentially."
}

The cursor workaround

Beyond the cap, switch to cursor pagination using the values every page's page_metadata already includes:

{
  "spending_level": "awards",
  "limit": 2,
  "results": [ ... ],
  "page_metadata": {
    "page": 1,
    "hasNext": true,
    "last_record_unique_id": 295527116,
    "last_record_sort_value": "4277416823125"
  }
}

Pass those two values back on the next request instead of incrementing page:

{
  "filters": { ... },
  "fields": [...],
  "sort": "Award Amount",
  "order": "desc",
  "limit": 100,
  "last_record_sort_value": "4277416823125",
  "last_record_unique_id": 295527116
}

This cursor approach has no 50,000-row ceiling — it's the only way to walk a result set larger than that through this endpoint. Combine it with the short-page stopping rule above (not hasNext) for a pull that neither errors out nor silently truncates.

limit caps at 100

The per-page limit parameter has a hard ceiling of 100. Requesting 101 doesn't get silently clamped to 100 — it returns an HTTP 422 error. Use 100 as your page size when you want the fewest possible requests.

Money semantics: obligated vs. outlays vs. ceiling

This is the single most common source of confusion in USAspending data, and it trips up experienced analysts, not just newcomers.

Practical rule: if you're building anything that displays "how much is this award worth," default to Award Amount (obligated) and label it as such — don't call it "value" or "total funding" without qualification, and never conflate it with outlays or an assumed ceiling.

Award type codes reference

Pass the codes for the category you want in award_type_codes. Contracts (A/B/C/D) and grants (02/03/04/05) have different valid fields/sort sets — see the fields section above — so query them as separate requests if you need both, rather than mixing codes in one call.

Auth, rate limits, being polite

• No API key required. Every call in this document, including the ones that intentionally triggered errors, was made with no authentication whatsoever.
• No rate-limit headers observed on any of our test responses, and no documented rate limit as of this writing. That's a reason for caution, not a license to hammer the endpoint — this is shared federal infrastructure.
• Space out requests. A ~150ms delay between paginated calls is enough to be polite without meaningfully slowing a real pull; that's what we use in production.
• Retry with backoff on 429/5xx, never in a tight loop. Treat non-2xx, non-retryable errors (like the 422/400s documented above) as signals to fix the request, not to retry.
• Use a real, identifying User-Agent header on production traffic.

Worked example: a full paginated pull

Putting the short-page stopping rule and the field-discovery technique together, a correct pull for all contract awards in a date window looks like:

const PAGE_LIMIT = 100;
const MAX_PAGEABLE_RESULTS = 49900; // stay under the 50,000 hard cap

async function fetchAllContracts(startDate, endDate) {
  const filters = {
    award_type_codes: ['A', 'B', 'C', 'D'],
    time_period: [{ start_date: startDate, end_date: endDate }],
  };
  const results = [];
  let page = 1;
  let pageWasFull = true;

  while (pageWasFull) {
    if (page * PAGE_LIMIT > MAX_PAGEABLE_RESULTS) break; // switch to cursor pagination here if needed

    const res = await fetch('https://api.usaspending.gov/api/v2/search/spending_by_award/', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        filters,
        fields: ['Award ID', 'Recipient Name', 'Award Amount', 'Total Outlays', 'Awarding Agency'],
        sort: 'Award Amount',
        order: 'desc',
        page,
        limit: PAGE_LIMIT,
      }),
    }).then(r => r.json());

    results.push(...res.results);
    // Correct stop condition — NOT res.page_metadata.hasNext:
    pageWasFull = res.results.length === PAGE_LIMIT;
    page += 1;
  }
  return results;
}

This is a simplified version of the real fetcher behind open-fedspend-data, which adds retry-with-backoff and request throttling.