Get National Debt
treasury_get_debtRead-onlyIdempotent
Fetch national debt (Debt to the Penny) — total public debt outstanding broken into publicly-held debt and intragovernmental holdings. Three modes: "latest" returns the most recent business day's record; "date" returns the record for a specific date (must be a business day — the API only records debt on days markets are open); "series" returns a date range, staging the full result as a DataCanvas table when canvas_id is set or the range matches more than 500 rows — read the table's column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query. Records go back to 1993-04-01.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ISO 8601 date (YYYY-MM-DD) for mode=date. Must be a business day; the API only records debt on days the market is open. | |
| mode | No | "latest" returns the most recent day's record. "date" returns the record for a specific date. "series" returns a date range — use with start_date and end_date. | latest |
| end_date | No | ISO 8601 end date for mode=series (inclusive). Defaults to today. | |
| canvas_id | No | Set any non-empty value to stage mode=series results as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. Staging also happens on its own when the range matches more than 500 rows. The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Requires CANVAS_PROVIDER_TYPE=duckdb. | |
| start_date | No | ISO 8601 start date for mode=series (inclusive). Fiscal Data has daily debt records back to 1993-04-01. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The preview cap applied to the inline series array. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Series rows returned inline. | |
| notice | No | Guidance when the inline series is a preview, when the series was staged as a DataCanvas table, or when paging stopped before the full matched set. | |
| series | No | Inline preview of the mode=series records — at most 20 rows, newest first. Compare series.length against retrieved_records to detect the cap; the full retrieved set is reachable through canvas_id when one is returned. | |
| canvas_id | No | DuckDB table name (df_XXXXX_XXXXX) holding the full retrieved series. Pass it to treasury_dataframe_describe for the column schema, then use it as the FROM target in treasury_dataframe_query SQL. Absent when nothing was staged. | |
| truncated | No | True when the inline series array holds fewer rows than were retrieved. | |
| total_debt | No | Total public debt outstanding in USD, as a plain decimal string — no separators, no currency symbol, two decimal places. Convert as needed. | |
| record_date | No | Date of this debt record (YYYY-MM-DD). For series mode, the most recent date. | |
| total_records | No | Records matching the date range upstream. Exceeds retrieved_records when the match is larger than the series row bound. | |
| debt_held_public | No | Debt held by the public (external creditors, Fed, foreign governments) in USD. | |
| canvas_expires_at | No | ISO 8601 expiry for the canvas dataframe. | |
| retrieved_records | No | Records actually fetched for mode=series across every page, and the row count of the canvas table when one was registered. Never larger than total_records. | |
| intragovernmental_holdings | No | Intragovernmental holdings (debt owed to federal trust funds, Social Security, etc.) in USD. |