# Budget

!!! warning "Beta — surface may change"
    The `/api/budget/...` endpoints and the `/api/entities/{uei}/budget-flows/` action are **beta**. Data is real and refreshed on the normal cadence, but field names, shape leaves, default fields, filter names, and URL paths may still change based on early-consumer feedback. Pin a specific request shape (`?shape=...`) in production code, and watch the [changelog](../CHANGELOG.md) for the move-to-stable announcement.

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](../guides/how-to/explore-federal-budget.md). For field definitions, see the [Budget Data Dictionary](../data-dictionary/budget.md).

## 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](organizations.md).

## Filtering

| Param | What it does |
| --- | --- |
| `search` | Free-text search across `account_title`, `agency_name`, `bureau_name`. |
| `federal_account_symbol` | Exact match (also `__in` for multi). E.g. `075-0512`. |
| `fiscal_year` | Exact match, also `__in`, `__gte`, `__lte`. |
| `agency_code` | CGAC 3-character code. `__in` for multi-agency queries. |
| `bureau_name` | Exact, `__in`, or `__icontains` for fuzzy matching. |
| `account_title` | `__icontains` for fuzzy matching on account title. |
| `bea_category` | BEA budget enforcement category (`Defense`, `Nondefense`, `Mandatory`, ...). |
| `on_off_budget` | `ON` or `OFF` budget. |
| `subfunction_code` | OMB budget subfunction code (e.g. `051`, `551`). |

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](../data-dictionary/budget.md) for what each field means and the [exploration guide](../guides/how-to/explore-federal-budget.md) 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](../guides/patterns/response-shaping.md) 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:**

| Expand | Returns | Notes |
| --- | --- | --- |
| `appendix(*)` | President's Budget Appendix object-class breakdown (16 OMB request buckets — personnel comp, travel, contractual services, grants, etc. — plus granule ID and PDF URL). | `null` for accounts with no Appendix data (typically large mandatory programs). Coverage: FY08–FY27. |
| `narratives(*)` | List of Appendix narrative + appropriations text entries for this (FA, FY). | `null` when no narratives exist. ~5% of accounts have multiple narratives per year (split by subaccount). Text fields can be several KB each — only loaded when explicitly requested. |

```bash
# 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

```text
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:

| Field | Meaning |
| --- | --- |
| `funding_organization_id` | Organization UUID — resolvable via `/api/organizations/{key}/`. |
| `funding_office` | Hydrated payload with full Department / Agency / Office hierarchy for the funding org. |
| `recipient_id` | UEI — resolvable via `/api/entities/{uei}/`. |
| `recipient` | Hydrated payload with `uei`, `legal_business_name`, `dba_name`. |
| `contract_obligated`, `contract_outlayed` | Dollar flows. |
| `n_contracts` | Distinct PIID count under this (FA, funding office, recipient). |
| `contracts[]` | Minimal `Contract` shape per PIID — `key`, `piid`, `naics`, `psc`, `obligated`, `award_date`. Use `key` to follow back to the full Contract record. |

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

```text
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.

| Field | Meaning |
| --- | --- |
| `tas` | Full Treasury Account Symbol including appropriation year. |
| `quarter` | `1` through `4`. |
| `period` | `quarterly` or `cumulative` — both shapes are returned per quarter. |
| `obligated_quarterly`, `outlayed_quarterly` | Flow during the quarter. |
| `obligated_cumulative`, `outlayed_cumulative` | Running total through end of the quarter. |
| `quarterly_source` | Provenance flag — which SF-133 snapshot the row came from. |

**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

```text
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

| Surface | Years covered |
| --- | --- |
| `/api/budget/accounts/` lifecycle | FY17–FY26 |
| `appendix(*)` shape leaf | FY08–FY27 |
| `narratives(*)` shape leaf | FY08–FY27 |
| `/quarters/` | FY21+ |
| `/recipients/`, `/budget-flows/` | FY17–FY26 |

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](../guides/how-to/explore-federal-budget.md) for curl + Python `requests` recipes.