Skip to content

Budget Data Dictionary

Beta — surface may change

The /api/budget/... endpoints are beta. Field names, defaults, and groupings may still change. See the API reference and the exploration guide.

Field-level definitions for /api/budget/accounts/ and its nested actions. For the request/response shape and filter syntax, see the Budget API reference.

Overview

Each row in /api/budget/accounts/ is one (federal account × fiscal year) snapshot of the full appropriation pipeline, with FPDS contract activity joined in. A "federal account" here is the Treasury federal account — the standard {agency_cgac}-{account_number} grouping (e.g. 075-0512 = HHS NIH research).

Update frequency

Source Cadence
Lifecycle (requested / enacted / apportioned / obligated / outlayed) Refreshed when upstream SF-133, MAX, and Treasury sources update — typically monthly, faster during budget season.
Contract / assistance breakdown Refreshed when the upstream FPDS-to-account join recomputes — typically nightly.
Appendix object-class detail Refreshed once per Budget cycle (annual + supplementals).
Quarterly TAS detail (/quarters/) Refreshed quarterly when Treasury publishes SF-133.

Identity

Field Type Description
federal_account_symbol String Canonical key. Format {agency_cgac}-{account_number} (e.g. 075-0512).
fiscal_year Integer Fiscal year of the snapshot.
data_through_period Integer (nullable) File A fiscal period (1–12) the account-year's figures run through. The latest fiscal year is partial until it reaches 12, and its mid-year figures for indefinite and trust-fund appropriations can run high until year-end, so check this before comparing it with closed years. null when the row has no File A data. Filters: exact, __gte, __lte, __isnull. The X-Tango-Data-As-Of response header gives the latest period across the publication.
agency_code String 3-character CGAC of the owning agency.
agency_name String Full name of the owning agency.
bureau_name String Bureau / sub-agency name as published in the source. Free text — use __icontains for fuzzy lookup.
account_title String Human-readable account name.
bea_category String BEA budget enforcement category (Defense, Nondefense, Mandatory, Net interest, ...).
on_off_budget String ON or OFF budget.
subfunction_code String OMB budget subfunction code (e.g. 051 = national defense, 551 = health care services).
account_category String budgetary, credit_financing, request_only or proposed. Credit financing accounts are non-budgetary: they carry apportionments but no obligations and no enacted_ba. request_only accounts are current-law accounts with a President's Budget request and no File A data (for example NIH 075-9915); proposed accounts are requests for programs Congress never created (for example the EV Fund 047-0623). Both carry requested_ba but have null execution figures and enacted_ba. Sum apportionments, obligations and enacted budget authority with account_category=budgetary; sum a current-law requested_ba with account_category__in=budgetary,request_only. See Account category.

Lifecycle dollars

The standard appropriation pipeline — what was asked for, what was authorized, what was released, what was spent, and what was paid out. Money fields are USD.

Field Type Description
requested_ba Float Budget authority requested by the President.
enacted_ba Float Budget authority enacted by Congress.
apportioned Float Amount OMB has apportioned (released to the agency to spend).
obligated_total Float Total obligated against this account.
outlayed_total Float Total outlayed (cash actually paid).
unobligated_balance Float Apportioned but not yet obligated.

Contract / assistance / unlinked breakdown

Breaks obligated_total and outlayed_total into the three flows tracked separately.

Field Type Description
contract_obligated Float Obligations attributable to contract awards (FPDS).
contract_outlayed Float Outlays attributable to contract awards.
n_contracts Integer Distinct contract count under this account-year.
n_unique_contract_recipients Integer Distinct UEIs receiving contract dollars.
assistance_obligated Float Obligations attributable to financial assistance (grants, loans, etc.).
assistance_outlayed Float Outlays attributable to financial assistance.
n_grants Integer Distinct grant count under this account-year.
n_unique_grant_recipients Integer Distinct recipient count on the assistance side.
unlinked_obligated Float Obligations that don't match either FPDS or USAspending assistance — internal transfers, misclassified rows, etc.
contract_share_of_obligated Float contract_obligated / obligated_total.
contract_share_of_obligated_capped Float Same ratio, bounded for sort/filter stability.
contract_share_capped_flag Boolean true when the cap was applied to this row.
assistance_share_of_obligated Float assistance_obligated / obligated_total.
assistance_share_of_obligated_capped Float Same ratio, bounded.
assistance_share_capped_flag Boolean true when the cap was applied.

Source anomalies

source_anomalies is an array in the default shape, [] when the account-year is clean. Each element names one problem found in the source data for this row. The set of codes may grow.

code Condition action
contract_exceeds_obligations USAspending File C contract obligations exceed the account's positive File A total obligations. contract_obligated is capped at obligated_total. capped
assistance_exceeds_obligations File C assistance obligations exceed positive File A total obligations (assistance_share_capped_flag is true). Values are served as reported. flagged
contract_without_obligations File C reports contract obligations for an account whose File A total obligations are zero or negative. Values are served as reported. flagged

Each element carries:

Field Type Description
code String The anomaly, from the table above.
field String The field the anomaly is about: contract_obligated for the two contract codes, assistance_obligated for assistance_exceeds_obligations.
bound_field String The field it was checked against. Always obligated_total.
action String capped (the served value was changed) or flagged (served as reported).
reported_value Float The value as the source reported it, rounded to cents.
served_value Float The value the API serves in field, rounded to cents. Equal to reported_value when action is flagged.
likely_cause String single_row_outlier when the largest File C row in source.rows is at least half the excess over obligated_total; otherwise file_c_ahead_of_file_a when File A has not reached period 12 for the fiscal year, so File C may include periods File A has not reported yet; otherwise unexplained. assistance_exceeds_obligations carries no rows, so it is never single_row_outlier.
affected_fields Array[String] The served fields the anomaly affects: field itself and the fields derived from it. Fixed per code.
message String Human-readable description of the anomaly. One fixed sentence per code.
source Object dataset (always usaspending_file_c), fiscal_year (Integer), and, for both contract codes, rows. assistance_exceeds_obligations has no rows key.
source.rows[] Array[Object] Up to three of the largest PIID-linked File C rows on the account and fiscal year, largest transaction_obligated_amount first; [] when none were found. Each row carries fiscal_period (Integer), piid (String), parent_piid (String), tas (String), reporting_agency_id (String), transaction_obligated_amount (Float, rounded to cents), and file_c_source (db_dump or bulk_zip). Every row field except piid and file_c_source can be null.

There is no filter on source_anomalies. source_anomalies, account_category and data_through_period may be empty or default ([], budgetary, null) until the next budget data refresh carries them.

Forward-look

The President's next-year request vs the current enacted level.

Field Type Description
next_year_requested_ba Float BA requested for the following fiscal year.
ba_growth_next_year Float next_year_requested_ba - enacted_ba (absolute dollar change).
ba_growth_next_year_pct Float Relative change ((next - current) / current).

Ratios (lifecycle)

Each lifecycle ratio ships in three variants: *_pct (raw), *_pct_capped (bounded for sort/filter stability — typically at 5.0), and *_pct_capped_flag (boolean — true when the cap was applied). Use raw for math, capped for filtering and visualization.

Field family Numerator / denominator What it tells you
enacted_to_requested_pct enacted_ba / requested_ba Did Congress give more (>1.0) or less (<1.0) than the President asked?
apportioned_to_enacted_pct apportioned / enacted_ba How much of enacted has OMB released to spend?
obligated_to_apportioned_pct obligated_total / apportioned How much of released funds have been committed?
obligated_to_enacted_pct obligated_total / enacted_ba How much of authorized funds have been committed?
outlayed_to_obligated_pct outlayed_total / obligated_total How much of committed funds have actually been paid out?
unobligated_pct unobligated_balance / apportioned Reciprocal pipeline-pressure signal.

Year-over-year and 5-year movement signals. These are an opt-in shape cluster — pass them in ?shape= to include them in the response.

Field Type Description
enacted_ba_yoy_pct Float Year-over-year change in enacted BA vs prior FY.
obligated_yoy_pct Float Year-over-year change in total obligations.
contract_obligated_yoy_pct Float Year-over-year change in contract-side obligations.
enacted_ba_5yr_cagr Float 5-year compound annual growth rate of enacted BA.
contract_obligated_5yr_cagr Float 5-year CAGR of contract obligations.

Request-vs-actual (contract side)

How the President's requested split of contractual services compares to actual contract spending. Opt-in cluster.

Field Type Description
requested_contractual_services Float Object-class amount requested for contractual services.
requested_personnel_share Float Ratio of requested personnel comp to total request.
actual_vs_requested_contract Float contract_obligated / requested_contractual_services.
actual_vs_requested_contract_capped Float Same, bounded.
actual_vs_requested_contract_capped_flag Boolean true when the cap was applied.

Provenance + narrative

Field Type Description
appendix_pdf_url String URL to the President's Budget Appendix PDF for this account.
account_narrative_excerpt String Short excerpt from the appendix narrative. For full text use the narratives(*) shape leaf.
top_contract_recipients Array[String] Lightweight name-only list of top contract recipients. Sparse (null when no recipients resolve to names). Use the /recipients/ drill-down for analytical work — it carries UEI, hydrated entity payload, PIIDs, and the full Contract records.
top_grant_recipients Array[String] Lightweight name-only list of top grant recipients.
created, modified Datetime Standard timestamps.

Shape leaves

These are expansion leaves, not flat fields. Pass appendix(*) or narratives(*) inside ?shape=... to include them.

appendix(*) — President's Budget Appendix object-class breakdown

Returns a payload with all 16 OMB object-class request buckets plus appendix metadata. Coverage: FY08–FY27. Returns null for accounts with no Appendix data (typically large mandatory programs like Medicaid).

Object-class buckets include: personnel comp, civilian personnel benefits, military personnel benefits, travel, transportation of things, rents/communications/utilities, printing, contractual services, supplies, equipment, land/structures, investments and loans, grants and subsidies, insurance claims, interest and dividends, refunds.

Metadata: appendix_granule_id, appendix_pdf_url.

narratives(*) — Appendix narrative + appropriations text

Returns a list (some accounts have 2–3 narratives per year, split by subaccount). Each item carries the narrative text and the appropriations language. Text can run a few KB per field — only loaded when the leaf is in the request.

Nested action payloads

These are returned by /recipients/ and /quarters/, not on the account detail itself. Documented in the API reference.

Surface Shape per row
/recipients/ funding_organization_id, funding_office{...}, recipient_id (UEI), recipient{...}, contract_obligated, contract_outlayed, n_contracts, contracts[] (minimal Contract per PIID)
/quarters/ tas, quarter, period, obligated_quarterly, outlayed_quarterly, obligated_cumulative, outlayed_cumulative, quarterly_source

Data sources

Source What we use it for
OMB MAX A-11 / President's Budget requested_ba, next_year_requested_ba, Appendix object-class detail, narrative text, appendix_pdf_url.
Treasury SF-133 enacted_ba, apportioned, obligated_total, outlayed_total, unobligated_balance, and the entire /quarters/ surface.
FPDS (federal contract awards) contract_obligated, contract_outlayed, n_contracts, n_unique_contract_recipients, the /recipients/ drill-down, and the entity /budget-flows/.
USAspending File C Cross-reference for matching FPDS obligations to specific TAS / federal accounts; backs the unlinked_obligated calculation.
Report an issue with this page