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.
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).

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.

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