Feedback from a budget-execution monitoring use case (obligation pace + OpenOMB join)

[abigailhaddad]

Fourth in the series (#29, #30, #38). #38 was about replicating the budget-endpoint blog posts; this one is from building budget-execution analysis on top of it — two concrete artifacts:

1. An OpenOMB → Tango join: take an account OMB has restricted in an apportionment (OpenOMB surfaces the footnote) and pull the contractors that account pays (Tango), on the shared federal_account_symbol.
2. An obligation-pace monitor: sweep contract-heavy discretionary accounts and flag any whose cumulative obligations are running materially behind their own prior-year pace at the same fiscal quarter (the test that caught ED Student Aid 091-0202 at −36% vs FY2025).

tango-python v1.1.1, a few hundred calls. None of this blocks the work — workarounds exist — but these are the things that made budget-execution analysis (as opposed to point lookups) harder than it needed to be. The items here are new; they don't overlap #38.

---

What worked well for this use case

• federal_account_symbol ↔ OpenOMB Agency+Account is a clean join key. This is the entire reason the OpenOMB integration was trivial — OpenOMB has the apportionment footnotes Tango doesn't carry, Tango has the award layer OpenOMB doesn't, and they line up one-to-one on the account symbol. Please don't change that key.
• quarters/ reproduces SF-133 by TAS, with the period of availability encoded in the TAS string (075-2025/2025-… one-year vs 075-X-… no-year). That made an obligation-pace comparison possible at all, and let us classify expiring vs. carryover money without a separate source.
• Hydrated contracts on recipients/ (piid, description, total_contract_value, obligated) let us say concretely what an account buys, not just who it pays.

---

Friction (ranked by impact on this use case)

1. 🔴 recipients/ is contracts-only — no grant/assistance recipients

recipients/ returns only contract awardees. There is no equivalent for assistance: assistance_obligated exists at the account level, but no recipient breakdown hangs off it, and list_grants returns grants.gov opportunities (e.g. {"opportunity_number":"RDRUS-26-RFP","status":"Posted"}), not awarded grantees by account.

Why it bit: in our OpenOMB work, 168 of 169 spend-plan-restricted FY2026 accounts are grant/benefit programs (child nutrition, refugee assistance, foster care, SSI, …). For all of them the recipient drill-down returns nothing — exactly the accounts where "who gets this money" matters most, and the answer is "states and grantees" that Tango can't name here.

Ask: an assistance-recipients surface (funding-office × grantee, like the contract one), or — at minimum — document that recipients/ covers contracts only so users don't read an empty result as "no recipients."

2. 🔴 No batch / time-series access to quarterly obligations

quarters/ is per-account-per-year only (accounts/{id}/quarters/), and id is per (account, fiscal_year) (#38 item 5). So any cohort or longitudinal question — "which accounts are obligating behind prior years?" — is N accounts × M years of drill-down calls, each preceded by an id resolution.

Repro (our monitor): 69 candidate accounts × 3 fiscal years ⇒ a 3-year accounts/ sweep for ids plus ~200 quarters/ calls, and with the burst rate limit (Rate limit exceeded for burst. Please try again in 47 seconds.) the full scan runs ~15 minutes. Caching prior years (which don't change) helps reruns but not the first pass.

Ask (highest-impact item here): either expose a pace field on the accounts/ list response — cumulative-obligated-by-quarter, or a derived obligated_same_quarter_prior_year — so cohort pace analysis is one paginated sweep instead of hundreds of drill-downs; or a batch/filterable quarters endpoint (e.g. quarters/?fiscal_year=&federal_account_symbol__in=). This is the single biggest blocker for budget-execution monitoring.

3. 🟠 quarters/ open-year forward-fill has no "as-of" marker — and it caused a real bug

In the open year, quarters/ forward-fills future quarters with the latest actual (Q3==Q4==latest real, noted in #38). But there's no flag saying which quarter is the last actual one, and a genuinely flat quarter (zero obligations that quarter) is indistinguishable from "not yet reported."

Consequence: our first pass detected the latest-real quarter per account by finding where cumulative stops increasing — and that silently picked Q1 for some accounts and Q2 for others, producing nonsense pace ratios (e.g. 63,000%) before we caught it and pinned all accounts to one global as-of quarter.

Ask: an explicit as_of_quarter (or is_actual per row) on quarters/, ideally tied to the File A/B reporting period. One field removes the guesswork and the failure mode.

4. 🟡 get_contract carries no period-of-performance / end dates

get_contract returns piid, description, award_date, total_contract_value, naics_code, psc_code, obligated. Every shape request for performance dates is rejected:

client.get_contract(KEY, shape="piid,total_contract_value,period_of_performance(current_end_date,potential_end_date)")
# TangoValidationError: Invalid request parameters: Invalid shape

So you can't tell whether a contract is expiring — which blocks "about to recompete / about to end" analysis, the natural pairing with the appropriated-but-unobligated "pipeline" framing in the blog posts. (We could see what the account buys and how much is obligated, but not until when.)

Ask: expose period-of-performance start / current-end / potential-end on the contract shape.

5. 🟡 budget-flows is funding-office × account × year grain — duplicate years on naive aggregation

Reversing a vendor (get_entity_budget_flows), the same (federal_account_symbol, fiscal_year) repeats once per funding office, so a naive "obligated by year" sum double-handles years (we saw a vendor's FY2025 appear twice with different amounts before grouping by office). Not wrong, but a doc note on the grain — or an optional account×year aggregated view — would save the surprise.

---

Wishlist (in priority order)

1. A pace field on accounts/ (or a batch quarters endpoint) so obligation-pace cohort analysis isn't hundreds of calls (item 2).
2. An assistance-recipients surface, or docs that recipients/ is contracts-only (item 1).
3. as_of_quarter / is_actual on quarters/ (item 3).
4. Period-of-performance fields on the contract shape (item 4).

What Tango made possible here

The budget-execution monitor — flagging accounts obligating behind their own prior-year pace — is a genuinely useful thing to watch, and it came out of quarters/ + the stable account-symbol join with no other source needed for the pace itself. The asks above are about doing it at the scale of "all buying accounts, every quarter" rather than one account at a time.

[abigailhaddad]

Follow-up finding (same use case): requested_ba is empty for FY2026, and the forward-looking request fields return garbage for the current year.

Building the "intent" leg of a power-of-the-purse analysis — President requested vs. Congress enacted, per account — requested_ba vs enacted_ba is exactly the field pair you'd want. It works for settled years but is missing/wrong for the current one.

Populated and sane for FY2024 / FY2025:

client.list_budget_accounts(fiscal_year=2024, ordering="-requested_ba",
    shape="federal_account_symbol,requested_ba,enacted_ba", limit=1)
# 028-8006  requested_ba $1.31T  enacted_ba $1.31T   ✓ (and FY2025 similar)

Empty for FY2026 — and silently, as 0 rather than null:

client.list_budget_accounts(fiscal_year=2026, ordering="-requested_ba",
    shape="federal_account_symbol,account_title,requested_ba,enacted_ba", limit=3)
# 020-0500 Public Debt Principal          requested_ba 0   enacted_ba $1.26T
# 075-0512 Grants to States for Medicaid   requested_ba 0   enacted_ba $771B

Nobody "requests $0" for Public Debt Principal or Medicaid — so requested_ba=0 here means not loaded, not a real request of zero. The whole FY2026 column is 0.

The forward-looking fields are worse — negative BA and nonsensical growth on FY2026 rows:

013-0563 Digital Equity            next_year_requested_ba = -$2.21B   ba_growth_next_year_pct = -502%
089-0321 DOE Energy Eff./Renewable next_year_requested_ba = -$3.09B   ba_growth_next_year_pct = -180%

Why it matters for this use case: request-vs-enacted is the one leg of an impoundment / power-of-the-purse argument that has to come from the budget request (Intent → Congress overrides → OMB restricts → obligations lag). It's missing for exactly the fiscal year you'd be analyzing live, and the forward fields can't be trusted as-is — so right now you'd have to source the FY2026 President's Budget request separately, which defeats the "one API, already joined" value.

Asks:

1. Load FY2026 request data (and the FY2027 next-year request), per the announced FY2008–2027 appendix coverage.
2. Return null, not 0, for unpopulated requested_ba. 0 is a meaningful value (a proposed elimination), so conflating "not loaded" with "requested zero" silently corrupts any intent analysis — we briefly read it as "the President proposed to zero Digital Equity" before catching it on the Public-Debt sanity check. (Same silent-conflation risk as the unknown-filter behavior in Feedback from building a pocket-rescission watchlist on the new budget endpoint #38.)
3. next_year_requested_ba / ba_growth_next_year_pct should not emit negative budget authority or >100%-magnitude growth — looks like a current-year computation/coverage artifact.

[abigailhaddad]

Follow-up finding: recipients/ contract_obligated doesn't reconcile with USASpending File C / FPDS, and the docs don't define it precisely enough to reproduce.

Trying to validate the recipient dollar figures against the public source, we couldn't reproduce them — by any of four reasonable methods, all 2–3× off.

Test case: account 091-0202 (Student Aid Administration), recipient Accenture Federal Services LLC, FY2026.

Method (USASpending public endpoints)	FY2026 obligation
Tango recipients/ → contract_obligated	$77.5M
File C (/api/v2/awards/funding/), reporting-period FY, federal_account=091-0202 only	~$165M
FPDS action-date FY × File C 091-0202 account share (the data-dictionary's own definition)	~$179M
FPDS action-date FY (/api/v2/transactions/), all accounts on these awards	~$223M

The method that should match the dictionary — "Obligations attributable to contract awards (FPDS)" matched to the account via File C — lands at ~$179M, still ~2.3× the reported $77.5M. So contract_obligated isn't a straightforward FPDS×File C attribution; it's a narrower computation we can't derive from the public data.

Why this is hard / why attribution matters: these awards are multi-account funded — Accenture's three 091-0202 contracts also draw on 091-0201, 091-0243, and 091-0249 — so attributing a multi-account award's obligations to one federal account is exactly the ambiguous step, and the specific choice drives the number.

What the docs say, and don't:

• Data dictionary: contract_obligated = "Obligations attributable to contract awards (FPDS)." contract_outlayed = "Outlays attributable to contract awards."
• API reference: rows are "one row per (funding office × recipient × this account-year)."
• Not specified: whether the FY basis is action-date FY (FPDS) or File C reporting-period FY; whether amounts are net of deobligations; and the attribution rule for multi-account awards. Those unspecified choices are the entire 2–3× gap.

Repro: resolve awards via spending_by_award with filters.tas_codes.require = [["091","091-0202"]] + recipient_search_text; then per award, /api/v2/awards/funding/ (File C, gives federal_account × reporting_fiscal_year × transaction_obligated_amount) and /api/v2/transactions/ (FPDS, gives action_date × federal_action_obligation). Happy to share the script.

Asks:

1. Document contract_obligated's exact definition: FY basis (action-date vs File C reporting period), deobligation netting, and the multi-account attribution rule.
2. Ideally reconcile against File C — a 2–3× gap on a clean, high-visibility account (federal student-loan servicing) suggests either a definition that needs surfacing or an attribution issue. As is, the per-recipient dollar figures aren't independently reproducible from the public sources, even though the recipient list matches exactly.
3. Minor: the dictionary cites FPDS, which has been retired — contract data now flows through SAM.gov / USASpending.

(To be clear on scope: this is the recipients/ contract_obligated field only. The account-level quarters/ obligation figures — File A — are a separate matter and aren't implicated here.)

[abigailhaddad]

Question: how should we read quarters/ for the open fiscal year? Closed years reconcile with File A exactly; the current year doesn't, and we're not sure why.

We've been using quarters/ (which reports quarterly_source: usaspending_file_a) for in-year obligation pace, and sanity-checked it against USASpending's File A directly. For closed years it matches to the dollar; for the open year (FY2026) it diverges. We don't know whether that's expected — a load snapshot / data vintage, a definitional difference, or something worth flagging — so this is a clarification request, not a bug report.

Account 091-0202 (Student Aid Administration), cumulative obligations at quarter:

	USASpending File A (Spending Explorer)	Tango quarters/
FY2024 Q2	$1,239.5M	$1,240M ✓
FY2025 Q2	$889.5M	$890M ✓
FY2026 Q1	$85.5M	$200M
FY2026 Q2	$1,292.6M	$569M

Closed years are exact — that's great, and it's why we trusted the field. FY2026 is off in both quarters (Q2 by ~2.3×) and not in a way that looks like a simple one-quarter lag. The practical effect: an in-year pace comparison reads FY2026 as ~36% behind FY2025 off quarters/, versus ~45% ahead off File A — opposite conclusions, on exactly the open-year signal we care about most.

Repro for the USASpending side: POST /api/v2/spending/ with {"type":"federal_account","filters":{"fy":"2026","quarter":"2"}}, then the row with code 0202 / "…Education" (cumulative obligations through that quarter).

What we'd love to understand:

1. How is the open fiscal year in quarters/ populated and refreshed — a periodic snapshot? Is there an as-of date we can read? (Ties to the earlier ask for an as_of_quarter / is_actual marker — if the open year is a point-in-time load, that flag would let us tell.)
2. Is there a current-year definitional difference (a different File A vintage, netting, etc.) that explains the gap, or should current-year quarters/ track USASpending File A as closely as the closed years do?
3. Recommended way to use quarters/ for in-year pace in the meantime — or should we pull File A directly for the open year?

Closed-year accuracy is excellent; we just want to know how to read the current year before we build pace monitoring on it.