Skill Tracer
Skills › Scientific Agent Skills › usfiscaldata › datasets-debt.md

datasets-debt.md

185 lines · skills/usfiscaldata/references/datasets-debt.md at 5f2bc03

Open on GitHub
1# Debt Datasets — U.S. Treasury Fiscal Data
2

Debt Datasets — U.S. Treasury Fiscal Data

Raw lines 1 to 2
3## Debt to the Penny
4
5**Endpoint:** `/v2/accounting/od/debt_to_penny`
6**Frequency:** Daily
7**Date Range:** 1993-04-01 to present
8
9Tracks the exact total public debt outstanding each business day.
11**Key fields:**
12| Field | Type | Description |
13|-------|------|-------------|
14| `record_date` | DATE | Date of record |
15| `debt_held_public_amt` | CURRENCY | Debt held by the public |
16| `intragov_hold_amt` | CURRENCY | Intragovernmental holdings |
17| `tot_pub_debt_out_amt` | CURRENCY | **Total public debt outstanding** |
19```python
20# Current national debt
21resp = requests.get(
22 "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny",
23 params={"sort": "-record_date", "page[size]": 1},
24 timeout=30,
26resp.raise_for_status()
27latest = resp.json()["data"][0]
28from decimal import Decimal
29print(f"As of {latest['record_date']}: ${Decimal(latest['tot_pub_debt_out_amt']):,.2f}")
31# Preview of debt since January 2024; fetch_all() is needed for the full series
32resp = requests.get(
33 "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny",
34 params={
35 "fields": "record_date,tot_pub_debt_out_amt",
36 "filter": "record_date:gte:2024-01-01",
37 "sort": "-record_date"
38 },
39 timeout=30,
41resp.raise_for_status()
42df = pd.DataFrame(resp.json()["data"])
43df["tot_pub_debt_out_amt"] = df["tot_pub_debt_out_amt"].astype(float)
44```

Debt to the Penny

Endpoint: /v2/accounting/od/debt_to_penny Frequency: Daily Date Range: 1993-04-01 to present

Tracks the exact total public debt outstanding each business day.

Key fields:

FieldTypeDescription
record_dateDATEDate of record
debt_held_public_amtCURRENCYDebt held by the public
intragov_hold_amtCURRENCYIntragovernmental holdings
tot_pub_debt_out_amtCURRENCYTotal public debt outstanding
# Current national debt
resp = requests.get(
    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny",
    params={"sort": "-record_date", "page[size]": 1},
    timeout=30,
)
resp.raise_for_status()
latest = resp.json()["data"][0]
from decimal import Decimal
print(f"As of {latest['record_date']}: ${Decimal(latest['tot_pub_debt_out_amt']):,.2f}")

# Preview of debt since January 2024; fetch_all() is needed for the full series
resp = requests.get(
    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny",
    params={
        "fields": "record_date,tot_pub_debt_out_amt",
        "filter": "record_date:gte:2024-01-01",
        "sort": "-record_date"
    },
    timeout=30,
)
resp.raise_for_status()
df = pd.DataFrame(resp.json()["data"])
df["tot_pub_debt_out_amt"] = df["tot_pub_debt_out_amt"].astype(float)
Raw lines 3 to 45
46## Historical Debt Outstanding
48**Endpoint:** `/v2/accounting/od/debt_outstanding`
49**Frequency:** Annual
50**Date Range:** 1790 to present
52Annual record of U.S. national debt going back to the founding of the republic.
54**Key fields:**
55| Field | Type | Description |
56|-------|------|-------------|
57| `record_date` | DATE | Annual record date; historical fiscal-year conventions differ |
58| `debt_outstanding_amt` | CURRENCY | Total debt outstanding |
60```python
61# Full historical debt series (verify it fits in the requested page)
62resp = requests.get(
63 "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_outstanding",
64 params={"sort": "-record_date", "page[size]": 10000},
65 timeout=30,
67resp.raise_for_status()
68assert resp.json()["meta"]["total-pages"] <= 1, "Use fetch_all for more pages"
69df = pd.DataFrame(resp.json()["data"])
70```

Historical Debt Outstanding

Endpoint: /v2/accounting/od/debt_outstanding Frequency: Annual Date Range: 1790 to present

Annual record of U.S. national debt going back to the founding of the republic.

Key fields:

FieldTypeDescription
record_dateDATEAnnual record date; historical fiscal-year conventions differ
debt_outstanding_amtCURRENCYTotal debt outstanding
# Full historical debt series (verify it fits in the requested page)
resp = requests.get(
    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_outstanding",
    params={"sort": "-record_date", "page[size]": 10000},
    timeout=30,
)
resp.raise_for_status()
assert resp.json()["meta"]["total-pages"] <= 1, "Use fetch_all for more pages"
df = pd.DataFrame(resp.json()["data"])
Raw lines 46 to 71
72## Schedules of Federal Debt
74**Endpoint:** `/v1/accounting/od/schedules_fed_debt`
75**Frequency:** Monthly
76**Date Range:** October 2005 to present
78Monthly debt balances and activity by holder and classification. Do not sum opening/closing balances with activity lines. Unlike Debt to the Penny, these schedules exclude Federal Financing Bank debt; reconcile scope and units before comparing totals.
80**Key fields:**
81| Field | Type | Description |
82|-------|------|-------------|
83| `record_date` | DATE | End of month date |
84| `debt_holder_type` | STRING | Held by public or intragovernmental |
85| `security_class1_desc` | STRING | Primary classification or balance/activity line |
86| `security_class2_desc` | STRING | Secondary classification |
87| `principal_mil_amt` | CURRENCY0 | Principal, in millions of USD |
88| `accrued_int_payable_mil_amt` | CURRENCY0 | Accrued interest payable, in millions |
89| `net_unamortized_mil_amt` | CURRENCY0 | Net unamortized amounts, in millions |

Schedules of Federal Debt

Endpoint: /v1/accounting/od/schedules_fed_debt Frequency: Monthly Date Range: October 2005 to present

Monthly debt balances and activity by holder and classification. Do not sum opening/closing balances with activity lines. Unlike Debt to the Penny, these schedules exclude Federal Financing Bank debt; reconcile scope and units before comparing totals.

Key fields:

FieldTypeDescription
record_dateDATEEnd of month date
debt_holder_typeSTRINGHeld by public or intragovernmental
security_class1_descSTRINGPrimary classification or balance/activity line
security_class2_descSTRINGSecondary classification
principal_mil_amtCURRENCY0Principal, in millions of USD
accrued_int_payable_mil_amtCURRENCY0Accrued interest payable, in millions
net_unamortized_mil_amtCURRENCY0Net unamortized amounts, in millions
Raw lines 72 to 90
91## Schedules of Federal Debt by Day
93Two daily data tables under `/v1/accounting/od/`:
95| Table | Endpoint | Description |
96|-------|----------|-------------|
97| Daily Activity | `/v1/accounting/od/schedules_fed_debt_daily_activity` | Daily debt activity |
98| Daily Summary | `/v1/accounting/od/schedules_fed_debt_daily_summary` | Daily debt summary |
100**Related:** `/v1/accounting/od/schedules_fed_debt_fytd` — fiscal year-to-date schedules.

Schedules of Federal Debt by Day

Two daily data tables under /v1/accounting/od/:

TableEndpointDescription
Daily Activity/v1/accounting/od/schedules_fed_debt_daily_activityDaily debt activity
Daily Summary/v1/accounting/od/schedules_fed_debt_daily_summaryDaily debt summary

Related: /v1/accounting/od/schedules_fed_debt_fytd — fiscal year-to-date schedules.

Raw lines 91 to 101
102## Treasury Report on Receivables (TROR)
104**Endpoint:** `/v2/debt/tror`
105**Frequency:** Quarterly
106**Date Range:** December 2016 to present
108Federal agency compliance and receivables data. Also includes:
109- `/v2/debt/tror/data_act_compliance` — 120 Day Delinquent Debt Referral Compliance Report
111**Key fields:**
112| Field | Type | Description |
113|-------|------|-------------|
114| `record_date` | DATE | Quarter end date |
115| `funding_type_description` | STRING | Funding classification |
116| `receivable_type_description` | STRING | Receivable class |
117| `ddebt_by_age_total_amt` | CURRENCY | Delinquent debt total by age |
119```python
120# TROR data, sorted by funding type
121resp = requests.get(
122 "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/debt/tror",
123 params={"sort": "funding_type_id"},
124 timeout=30,
126resp.raise_for_status()
127```

Treasury Report on Receivables (TROR)

Endpoint: /v2/debt/tror Frequency: Quarterly Date Range: December 2016 to present

Federal agency compliance and receivables data. Also includes:

  • /v2/debt/tror/data_act_compliance — 120 Day Delinquent Debt Referral Compliance Report

Key fields:

FieldTypeDescription
record_dateDATEQuarter end date
funding_type_descriptionSTRINGFunding classification
receivable_type_descriptionSTRINGReceivable class
ddebt_by_age_total_amtCURRENCYDelinquent debt total by age
# TROR data, sorted by funding type
resp = requests.get(
    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/debt/tror",
    params={"sort": "funding_type_id"},
    timeout=30,
)
resp.raise_for_status()
Raw lines 102 to 128
129## Gift Contributions to Reduce the Public Debt
131**Endpoint:** `/v2/accounting/od/gift_contributions`
132**Frequency:** Monthly
133**Date Range:** September 1996 to present
135Records voluntary contributions from the public to reduce the national debt.

Gift Contributions to Reduce the Public Debt

Endpoint: /v2/accounting/od/gift_contributions Frequency: Monthly Date Range: September 1996 to present

Records voluntary contributions from the public to reduce the national debt.

Raw lines 129 to 136
137## Interest Expense on the Public Debt Outstanding
139**Endpoint:** `/v2/accounting/od/interest_expense`
140**Frequency:** Monthly
141**Date Range:** May 2010 to present
143Monthly interest expense broken down by security type.
145**Key fields:**
146| Field | Type | Description |
147|-------|------|-------------|
148| `record_date` | DATE | Reporting month end |
149| `expense_catg_desc` | STRING | Public issues or government account series |
150| `expense_group_desc` | STRING | Expense group/accounting basis |
151| `expense_type_desc` | STRING | Expense component |
152| `month_expense_amt` | CURRENCY | Monthly expense in USD |
153| `fytd_expense_amt` | CURRENCY | Cumulative fiscal-year expense in USD |
155Use `month_expense_amt` for monthly flows, or the September `fytd_expense_amt`
156for a completed fiscal year. Preserve all three expense dimensions when checking
157the components. Never sum cumulative FYTD observations over months. This dataset
158uses modified accrual accounting and some GAS cash-basis entries; its expense
159measure is not the MTS budget net-interest measure. See the worked fiscal-year
160example in [examples.md](examples.md).

Interest Expense on the Public Debt Outstanding

Endpoint: /v2/accounting/od/interest_expense Frequency: Monthly Date Range: May 2010 to present

Monthly interest expense broken down by security type.

Key fields:

FieldTypeDescription
record_dateDATEReporting month end
expense_catg_descSTRINGPublic issues or government account series
expense_group_descSTRINGExpense group/accounting basis
expense_type_descSTRINGExpense component
month_expense_amtCURRENCYMonthly expense in USD
fytd_expense_amtCURRENCYCumulative fiscal-year expense in USD

Use month_expense_amt for monthly flows, or the September fytd_expense_amt for a completed fiscal year. Preserve all three expense dimensions when checking the components. Never sum cumulative FYTD observations over months. This dataset uses modified accrual accounting and some GAS cash-basis entries; its expense measure is not the MTS budget net-interest measure. See the worked fiscal-year example in examples.md.

Raw lines 137 to 161
162## Advances to State Unemployment Funds (Title XII)
164**Endpoint:** `/v2/accounting/od/title_xii`
165**Frequency:** Daily
166**Date Range:** October 2016 to present
168States and territories borrowing from the federal Unemployment Trust Fund.
170**Key fields:**
171| Field | Type | Description |
172|-------|------|-------------|
173| `record_date` | DATE | Date of record |
174| `state_nm` | STRING | State name |
175| `outstanding_advance_bal` | CURRENCY | Outstanding advance balance |

Advances to State Unemployment Funds (Title XII)

Endpoint: /v2/accounting/od/title_xii Frequency: Daily Date Range: October 2016 to present

States and territories borrowing from the federal Unemployment Trust Fund.

Key fields:

FieldTypeDescription
record_dateDATEDate of record
state_nmSTRINGState name
outstanding_advance_balCURRENCYOutstanding advance balance
Raw lines 162 to 176
177## Official sources
179Reviewed 2026-09-30 against the current dataset dictionaries and live API responses.
181- [Debt To The Penny](https://fiscaldata.treasury.gov/datasets/debt-to-the-penny/)
182- [Schedules Federal Debt](https://fiscaldata.treasury.gov/datasets/schedules-federal-debt/)
183- [Treasury Report On Receivables](https://fiscaldata.treasury.gov/datasets/treasury-report-on-receivables/)
184- [Interest Expense Debt Outstanding](https://fiscaldata.treasury.gov/datasets/interest-expense-debt-outstanding/)
185- [Ssa Title Xii Advance Activities](https://fiscaldata.treasury.gov/datasets/ssa-title-xii-advance-activities/)