Query Treasury Fiscal Data Dataset
treasury_query_datasetRead-onlyIdempotent
Query any Treasury Fiscal Data endpoint by path, field list, filters, sort, and page. Call treasury_list_datasets first to get the correct endpoint path and exact field names — a typo in either causes a 400. Filter syntax: each condition is { field, operator, value } where operator is eq/gt/gte/lt/lte/in (e.g., record_date:gte:2024-01-01). Multiple conditions are ANDed together. All response values are strings per the API contract, including numbers and dates; "null" (string) means no value. Supply canvas_id to stage the page result as a DataCanvas table — read its column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query (requires CANVAS_PROVIDER_TYPE=duckdb on the server).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort expression: field name optionally prefixed with "-" for descending (e.g., "-record_date" for newest-first). | |
| fields | No | Fields to return. Omit to return all fields. Specify field names exactly as listed by treasury_list_datasets — a typo causes a 400. | |
| filters | No | Filter conditions (ANDed together). Multiple filters on different fields are combined in one filter= parameter. | |
| endpoint | Yes | Endpoint path returned by treasury_list_datasets (e.g., "/v2/accounting/od/debt_to_penny"). Include the leading slash. | |
| canvas_id | No | Set any non-empty value to stage this page as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Omit to receive results inline only. Requires CANVAS_PROVIDER_TYPE=duckdb on the server. | |
| page_size | No | Rows per page. Default 100. Raise to 10000 to minimize round trips for small datasets. For large time-series pulls, use canvas_id with treasury_dataframe_query instead. | |
| page_number | No | Page to fetch (1-indexed). Check total_pages in the response to know if more pages exist. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Rows returned. All values are strings per API contract — including numeric and date fields. Convert in the calling context. Null values appear as the string "null". | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when results are empty, a field typo is suspected, the endpoint was not found in the catalog, or staging was requested. | |
| endpoint | No | Endpoint that was queried. | |
| canvas_id | No | DuckDB table name (df_XXXXX_XXXXX) holding this page. 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. | |
| page_size | No | Rows per page. | |
| totalCount | No | Total rows matching the query across all pages — discloses that this page is a subset. | |
| page_number | No | Current page (1-indexed). | |
| total_count | No | Total rows matching the query (across all pages). | |
| total_pages | No | Total pages at the current page_size. | |
| field_labels | No | Human-readable label for each returned field. | |
| applied_filters | No | Filter expression sent to the API, for verification. | |
| canvas_expires_at | No | ISO 8601 expiry for the canvas dataframe. |