Budget¶

Federal-account budget data — what Congress requested, what it enacted, what got apportioned, what's been obligated, and what's been outlayed — joined to FPDS contract activity. Each row is one (federal account × fiscal year).

For task-oriented walkthroughs, see Explore federal budget data. For field definitions, see the Budget Data Dictionary.

Endpoints¶

• GET /api/budget/accounts/ — list + filter + search.
• GET /api/budget/accounts/{pk}/ — detail.
• GET /api/budget/accounts/{pk}/recipients/ — funding-office × recipient drill-down with hydrated contracts.
• GET /api/budget/accounts/{pk}/quarters/ — TAS-grain SF-133 quarterly flow (FY21+).

Related budget surfaces on other resources:

• GET /api/entities/{uei}/budget-flows/ — federal accounts that paid a given vendor (the inverse of /recipients/). Documented below.
• GET /api/organizations/{key}/?shape=...,budget_appropriation(*),budget_spending(*) — org-level rollups. See Organizations.

Filtering¶

Every dollar and ratio field also supports __gte / __lte range filters. The full list of range-filterable fields:

• Dollars: requested_ba, enacted_ba, apportioned, obligated_total, outlayed_total, unobligated_balance, contract_obligated, contract_outlayed, assistance_obligated, assistance_outlayed
• Ratios (capped + raw): contract_share_of_obligated_capped, obligated_to_apportioned_pct(_capped), apportioned_to_enacted_pct(_capped), obligated_to_enacted_pct(_capped), outlayed_to_obligated_pct(_capped), unobligated_pct
• Trends: enacted_ba_yoy_pct, obligated_yoy_pct, enacted_ba_5yr_cagr, ba_growth_next_year_pct
• Request-vs-actual: actual_vs_requested_contract(_capped)

See Budget Data Dictionary for what each field means and the exploration guide for filter recipes.

Ordering¶

Pass ?ordering=<field> (prefix with - for descending). Allowed sort fields:

fiscal_year, agency_code, federal_account_symbol, enacted_ba, obligated_total, outlayed_total, contract_obligated, contract_share_of_obligated_capped, obligated_to_apportioned_pct_capped, obligated_to_enacted_pct_capped, ba_growth_next_year_pct, actual_vs_requested_contract_capped, enacted_ba_yoy_pct, enacted_ba_5yr_cagr, modified.

Default sort is -fiscal_year, -enacted_ba — the un-filtered list lands on the largest accounts of the most recent fiscal year.

Pagination¶

Standard page-number pagination: count / next / previous / results.

• page (default 1)
• limit (default 25, max 100)

Response shaping¶

This endpoint supports response shaping via ?shape=.

Default shape (no ?shape= param): identity fields + lifecycle dollars + the capped ratios that show up in the most common workflows + contract_obligated, contract_share_of_obligated_capped, assistance_obligated, ba_growth_next_year_pct.

On-demand expansions:

# Default shape
/api/budget/accounts/

# Pull everything
/api/budget/accounts/{pk}/?shape=*

# Detail + Appendix breakdown
/api/budget/accounts/{pk}/?shape=*,appendix(*)

# Detail + Appendix breakdown + narrative text
/api/budget/accounts/{pk}/?shape=*,appendix(*),narratives(*)

# Trends cluster
/api/budget/accounts/?shape=federal_account_symbol,account_title,enacted_ba,enacted_ba_yoy_pct,enacted_ba_5yr_cagr,contract_obligated_5yr_cagr

Recipients drill-down¶

GET /api/budget/accounts/{pk}/recipients/
GET /api/budget/accounts/{pk}/recipients/?funding_organization_id={org_uuid}

One row per (funding office × recipient × this account-year) on the contract side, sorted by contract_obligated desc. Each row carries:

The raw PIID array isn't surfaced — each contracts[] row carries its own piid, so the analytics-only consumer can reconstruct the list without bandwidth duplication.

Query params:

• funding_organization_id — Narrow to a single funding office (Organization UUID).
• limit — Page size (default 25, max 100).

Top-level response envelope includes federal_account_symbol and fiscal_year for context.

Quarterly cash flow¶

GET /api/budget/accounts/{pk}/quarters/
GET /api/budget/accounts/{pk}/quarters/?tas=075-2024-2024-0512

One row per (Treasury Account Symbol × quarter × period type) for this account-year. A federal account typically rolls up several TAS (different appropriation-year vintages), so the response is a list rather than a single record.

Coverage: FY21+. Earlier years return an empty page; use the account detail's lifecycle fields (obligated_total, outlayed_total) for FY17–FY20.

Query params:

• tas — Narrow to a single TAS.
• limit — Page size (default 25, max 100).

Entity budget-flows¶

GET /api/entities/{uei}/budget-flows/
GET /api/entities/{uei}/budget-flows/?fiscal_year=2024

The inverse of /recipients/ — given a UEI, list the federal accounts that paid this vendor. One row per (account × funding office × this UEI) flow, sorted by contract_obligated desc. Each row carries surrounding account context (account title, agency, bureau, BEA category, total enacted BA, contract share of obligated) plus the hydrated funding_office and contracts[] payloads (same shape as the recipients drill-down).

Contract-side only — grants and other assistance flows are not in this index.

Query params:

• fiscal_year — Restrict to one FY (omit for all years).
• limit — Page size (default 25, max 100).

This endpoint requires authentication.

Coverage windows¶

Out-of-range requests return empty lists or null-valued leaves — no error.

Capped vs raw ratios¶

Most ratio fields ship in three variants: *_pct, *_pct_capped, and *_pct_capped_flag. The capped variant bounds extreme values (typically at 5.0) so the field sorts and charts cleanly; the flag tells you whether the cap was applied for that row. Use raw when you need exact math, capped when filtering/sorting/visualizing.

SDK examples¶

The Python and Node SDKs don't yet expose first-class budget methods (beta). Use raw HTTP — see the exploration guide for curl + Python requests recipes.