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. Within a fiscal year, accounts with no enacted_ba (null) sort after every other account, and ties break on the account's id, so pages are stable. An explicit ?ordering= also sorts nulls last in both directions, and a field that is not in the list above returns 400 with the allowed fields rather than being ignored.

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 (including data_through_period, right after fiscal_year, and account_category) + 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 + source_anomalies.

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.

Partial fiscal years¶

data_through_period is the fiscal period (1–12) of USAspending File A that an account-year's figures run through, and null when the row has no File A data (for example, an account known only from apportionments or the Budget Appendix). Closed fiscal years read 12. The latest fiscal year is year-to-date and stays below 12 until it closes. The X-Tango-Data-As-Of header (below) names the latest period in the current publication. Until the data pipeline derives the period from the source, rows may carry 12 or null instead of the real period, so treat a value as a hint, not a guarantee.

A partial year is not comparable to a closed one. Beyond the missing months, mid-year figures for indefinite and trust-fund appropriations can run high and settle lower by year-end, so a partial-year enacted_ba can exceed the prior year's final figure without any real increase. Check data_through_period before comparing the latest year with earlier ones, or filter to complete years:

/api/budget/accounts/?fiscal_year__gte=2022&data_through_period=12

Responses also carry an X-Tango-Data-As-Of header with the latest fiscal year and period in the publication (e.g. 2026-P10), and X-Tango-Data-Published-At; both are omitted until a validated publication is live. The header describes the whole response, while data_through_period says it on every row.

Account category¶

account_category is one of four values:

All four are served and filterable. Which to include when you add rows up depends on the figure:

• Apportionment, obligation and enacted sums: use account_category=budgetary. Credit financing apportionments are not budget authority, so including them double-counts; request_only and proposed rows have null execution figures and add nothing.
• A current-law requested_ba total: use account_category__in=budgetary,request_only. Filtering to budgetary alone drops the request-only accounts, so the request comes out low. Leave credit_financing and proposed out.

/api/budget/accounts/?fiscal_year=2025&agency_code=075&account_category=budgetary
/api/budget/accounts/?fiscal_year=2027&agency_code=075&account_category__in=budgetary,request_only

The organization budget_appropriation(*) rollup follows the same rule: it leaves out credit financing and proposed accounts entirely, and adds request_only requested_ba to the department's request (request-only accounts are not counted in its other figures).

Source anomalies¶

source_anomalies is a list in the default shape, [] when the account-year is clean. Each element names one problem found in the source data for that row, and says whether Tango changed the served value (capped) or only reported the problem (flagged).

The list of codes may grow; treat an unknown code as a reason to look closer rather than an error. There is no filter on anomalies — read the field. Field-by-field definitions of each element are in the data dictionary.

"source_anomalies": [
  {
    "code": "contract_exceeds_obligations",
    "field": "contract_obligated",
    "bound_field": "obligated_total",
    "action": "capped",
    "reported_value": 1250000000.0,
    "served_value": 980000000.0,
    "likely_cause": "single_row_outlier",
    "affected_fields": [
      "contract_obligated",
      "contract_share_of_obligated_capped",
      "contract_obligated_yoy_pct",
      "contract_obligated_5yr_cagr",
      "actual_vs_requested_contract",
      "actual_vs_requested_contract_capped"
    ],
    "message": "USAspending File C contract obligations exceed this account's total obligations (File A). contract_obligated is capped at obligated_total; the excess most likely comes from a misreported File C row.",
    "source": {
      "dataset": "usaspending_file_c",
      "fiscal_year": 2025,
      "rows": [
        {
          "fiscal_period": 9,
          "piid": "EXAMPLE0001",
          "parent_piid": null,
          "tas": "000-X-0000-000",
          "reporting_agency_id": "000",
          "transaction_obligated_amount": 300000000.0,
          "file_c_source": "db_dump"
        }
      ]
    }
  }
]

Dollar amounts, PIID and TAS in the example are illustrative. Both contract codes carry source.rows: up to three of the largest PIID-linked File C rows on the account and fiscal year, largest first ([] when none were found). assistance_exceeds_obligations carries no rows.

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.