---
name: usaspending-api-ingestion
description: "How to get U.S. Treasury USAspending API data into a pandas DataFrame and Parquet: access, the request, the format, limits, quirks and terms."
---

# Load USAspending FY2026 contract obligations into Parquet

Source entry: https://signal-lab-jet.vercel.app/datasets/usaspending-api
Provider: https://api.usaspending.gov/docs/
Checked against the provider's documentation: 2026-11-01

## Access
- No account or key was required for the checked POST endpoint.
- The endpoint accepts JSON filters and returns aggregate JSON results plus coverage messages.

## Request
```bash
curl -X POST -H 'Content-Type: application/json' -d '{"group":"fiscal_year","filters":{"time_period":[{"start_date":"2025-10-01","end_date":"2026-09-30"}],"award_type_codes":["A","B","C","D"]},"spending_level":"transactions"}' 'https://api.usaspending.gov/api/v2/search/spending_over_time/'
```

## Format
JSON fiscal-year aggregates containing total and category-specific obligations or outlays, the spending level and provider messages about search coverage.

## Load into pandas and Parquet
Needs Python 3 with requests, pandas and pyarrow.
```python
"""USAspending FY2026 contract obligations -> pandas -> Parquet. No key."""
import requests
import pandas as pd

URL = "https://api.usaspending.gov/api/v2/search/spending_over_time/"
payload = {
    "group": "fiscal_year",
    "filters": {
        "time_period": [{"start_date": "2025-10-01", "end_date": "2026-09-30"}],
        "award_type_codes": ["A", "B", "C", "D"],
    },
    "spending_level": "transactions",
}
r = requests.post(URL, json=payload, timeout=60)
r.raise_for_status()
df = pd.json_normalize(r.json()["results"])
df.to_parquet("usaspending_contracts_fy2026.parquet", index=False)
print(len(df), "fiscal-year row", "FY", df.loc[0, "time_period.fiscal_year"],
      "contract obligations", f"${df.loc[0, 'Contract_Obligations']:,.2f}")
```
Run by us on 2026-11-01 (python 3.13.5 | pandas 3.1.0 | pyarrow 26.0.0 | requests 2.34.2). Result: 1 fiscal-year row FY 2026 contract obligations $768,293,510,588.91

## Limits
- Rate limit: Not stated.
- Award search time periods cannot begin before 2007-10-01; download and bulk-download routes extend to 2000-10-01.
- Some endpoints paginate or impose endpoint-specific result limits documented on their pages.

## Quirks
- Obligations and outlays are different measures; the checked transaction query returned obligation values and null outlay fields.
- Award totals can change as later transactions modify an award, so retain retrieval time and transaction-level identifiers for reproducible snapshots.
- Fiscal years begin on 1 October, and reporting cadence differs between award and account submissions.

## Terms and attribution
- USAspending describes the federal spending data served by the API as open source and public under the DATA Act.
- Retain source-system context because reporting exclusions, delays and later corrections affect interpretation.
- Terms page: https://github.com/fedspendingtransparency/usaspending-api/blob/master/README.md

## Sources
- https://api.usaspending.gov/: "The USAspending API (Application Programming Interface) allows the public to access comprehensive U.S. government spending data."
- https://www.usaspending.gov/data/data-sources-download.pdf: "Today, more than 100 federal agencies submit financial data to USAspending.gov on a monthly basis,"
- https://www.usaspending.gov/data/data-sources-download.pdf: "there is a 90-day delay in the submission of these data to the FPDS source system."
- https://github.com/fedspendingtransparency/usaspending-api/blob/master/README.md: "This API is utilized by USAspending.gov to obtain all federal spending data which is open source and provided to the public as part of the DATA Act."

## Help improve this skill
Missing a source, or see something to improve? Call the MCP tool suggest_source or feedback (or POST /api/suggest or /api/feedback). Reviewed ideas: https://signal-lab-jet.vercel.app/agent-suggestions

Information for educational purposes only. Free tiers, limits and licenses belong to the providers and may change; check the provider's own terms before using the data.