US Public Debt & Treasury Interest Rate History

Retrieve dated US public-debt totals and average Treasury security interest rates from the official Fiscal Data API, with exact debt amounts, units and source links.

Choose Debt to the Penny or Average Interest Rates, filter by date, sort the records and page through history. This actor is for Treasury accounting series. usaspending-awards concerns award recipients; world-bank-indicators concerns World Bank indicators. This actor returns neither of those, and does not collect exchange rates, recipient records or individual records.

Official sources

• Debt to the Penny: /v2/accounting/od/debt_to_penny.
• Average Interest Rates on U.S. Treasury Securities: /v2/accounting/od/avg_interest_rates.

The API host is https://api.fiscaldata.treasury.gov/services/api/fiscal_service. These are the two supported endpoints; there is no custom URL or endpoint input. No source API key is required.

What it returns

Each successful row represents one dated debt observation or one dated security-category rate. Dataset rows are available through the Actor's Results link and can be exported with Apify's dataset tools.

Field	Type	Meaning
status	string	ok or error
dataset	string	debt_to_penny or avg_interest_rates
recordDate	string	Treasury's observation date, YYYY-MM-DD
totalPublicDebt	string	Total public debt outstanding, exact USD decimal; debt rows
debtHeldByPublic	string	Debt held by the public, exact USD decimal; debt rows
intragovernmentalHoldings	string	Intragovernmental holdings, exact USD decimal; debt rows
averageInterestRate	number	Reported percentage, such as 7.577; rate rows
securityType	string	Treasury security type, such as Non-marketable; rate rows
securityDescription	string	Treasury security category, such as Domestic Series; rate rows
units	string	USD for debt or percent for rates
sourceEndpoint	string	Full official endpoint URL
sourceUrl	string	Official request URL including filters, sort and pagination
retrievedAt	string	UTC retrieval timestamp
errorCode	string	Error rows: invalid_record, request_failed or invalid_response
error	string	Error detail, without an untrusted response body
pageNumber	integer	Error rows: API page containing the failure

Debt amounts stay as decimal strings to preserve cents for these large totals. Rate numbers are percentages: 7.577 means 7.577%, not a fractional value of 0.07577. Fields for the other series are absent. Error rows can omit recordDate and value fields.

Input examples

The exact prefilled input is:

{"dataset":"debt_to_penny","sort":"-record_date","maxItems":5}

It requests page[size]=5 and starts at page one. An empty input object uses these defaults.

Historical category rates:

{
  "dataset": "avg_interest_rates",
  "startDate": "2026-01-01",
  "endDate": "2026-08-31",
  "securityType": "Marketable",
  "securityDescription": "Treasury Bills",
  "sort": "record_date",
  "pageSize": 5,
  "pageNumber": 1,
  "maxItems": 20
}

Input	Default	Behavior
dataset	debt_to_penny	Selects one supported Treasury series
startDate, endDate	No bounds	Inclusive record_date filters; optional YYYY-MM-DD dates
sort	-record_date	API fields separated by commas; - means descending
maxItems	5	Maximum dataset rows in this run, including errors; integer 1–100,000
pageSize	5	API rows per page; integer 1–1,000, capped to maxItems once
pageNumber	1	One-based starting page after filters and sort; integer 1–1,000,000
securityType	No filter	Exact security_type_desc, rates only
securityDescription	No filter	Exact security_desc, rates only

Sort fields: record_date for either series; debt also permits tot_pub_debt_out_amt, debt_held_public_amt and intragov_hold_amt; rates also permit security_desc, security_type_desc and avg_interest_rate_amt. Date and security fields are appended as stable tie-breaks when absent. Page size stays fixed across pages, including the final page. To continue a paginated export, keep the same filters, sort and effective page size. Category filters are exact source labels and apply only to the rates dataset.

Real output examples

This debt row was produced by the local prefill run on 2026-10-06. The complete five-row output is in sample_output.json.

{
  "dataset": "debt_to_penny",
  "sourceEndpoint": "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny",
  "sourceUrl": "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny?sort=-record_date&page%5Bsize%5D=5&page%5Bnumber%5D=1",
  "retrievedAt": "2026-10-06T08:30:33.306907+00:00",
  "units": "USD",
  "status": "ok",
  "recordDate": "2026-10-02",
  "totalPublicDebt": "40242446619209.33",
  "debtHeldByPublic": "32428913787327.44",
  "intragovernmentalHoldings": "7813532831881.89"
}

The separate local rates run produced this observation (selected fields; full row in evidence/behavior-results.json):

{
  "dataset": "avg_interest_rates",
  "status": "ok",
  "recordDate": "2026-08-31",
  "securityType": "Non-marketable",
  "securityDescription": "Domestic Series",
  "averageInterestRate": 7.577,
  "units": "percent"
}

Pricing

Proposed event: datapoint at 0.0005 USD per successful saved observation (0.50 USD for 1,000 custom events). Error rows and empty results do not trigger this event. The SDK spending limit stops further results when the custom event budget is exhausted. Platform costs depend on the published pricing configuration.

The observed comparable Store leader, fortuitous_pirate/treasury-fiscal-scraper, lists 0.00365 USD per result plus a 0.05 USD startup event in the 2026-10-06 API snapshot. It is tied for most total users and leads those ties by total runs. See PRICING.md for the ranking, other prices, exact event proposal and receipts. Pricing is a proposal until the owner activates monetization.

Limits and errors

Requests run serially, with one connection. Each request has a 30-second timeout and up to three attempts for network failures, HTTP 429 and server errors, using bounded backoff. Other HTTP failures return a source-linked error row. A malformed observation becomes an uncharged error row while subsequent records continue; a failed page returns an error row and stops that series. An empty date range produces no rows. Invalid inputs fail with a clear message before requesting data.

Output reflects records available from Treasury at run time. Publication delays and source revisions can change the latest available date or historical values. Average interest rates are Treasury accounting category averages, not daily market yield curves. No currency conversion, award-recipient enrichment or individual-level records are provided.

Use with AI agents / MCP

An AI agent can invoke the published Actor through Apify's MCP server or Actor API, pass the JSON input above, then read the dataset through the Results link. Give the agent the two allowed dataset values, a date range and a small maxItems cap. Preserve recordDate, units, sourceEndpoint and sourceUrl in any answer so the observation can be checked. This repository supplies an Actor; it does not run a separate MCP server.

FAQ

Why are debt amounts strings? The values are large; keeping the decimal text avoids losing cents through floating-point conversion. Use a decimal-aware tool when calculating with them.

Why can several rows have the same date? The rates series has one observation per Treasury security category on a record date. Stable category sorting makes pagination predictable.

Why is the latest rate older than today's date? The actor returns Treasury's published record_date, not a fabricated current observation. Check the source link and retrieval timestamp.

Can I fetch exchange rates or spending recipients? The supported sources are limited to Debt to the Penny and Average Interest Rates. There is no recipient, individual, exchange-rate or custom endpoint option.

Are local runs charged? The local SDK ignores charging without an active pay-per-event model. Configure the datapoint event before publishing. Actual paid billing and cloud execution have not been tested here.

Local development and verification

Dependencies are listed in requirements.txt. The designated project environment already contains them; no packages were installed into it.

From the actor directory in PowerShell, place the desired input in storage/key_value_stores/default/INPUT.json, then run:

$env:APIFY_LOCAL_STORAGE_DIR = "$PWD/storage"
& C:/GritWork/earn/.venv/Scripts/python.exe -m src
& C:/GritWork/earn/.venv/Scripts/python.exe -m pytest -q -p no:cacheprovider
apify validate-schema

Tests include real-response fixtures and @pytest.mark.live smoke tests for both endpoints. Recorded result: 37 passed in 2.87s on 2026-10-06 (evidence/tests-final.log). The prefill saved 5 rows; a fresh repeat took 2.3561 seconds locally (evidence/behavior-results.json). These are local observations, not performance guarantees.

Input and dataset schemas passed apify validate-schema in this actor directory. Apify CLI 1.10.0 does not discover the required outputSchema key; the same output file also passed the CLI through the compatibility descriptor in evidence/schema-validation. No Docker build, cloud run or publication was performed.