Treasury Fiscal Data paging: count is not the total, and links are not URLs

Checked 2026-09-08 · Rate limits, pagination walls and retries

page[size] tops out at 10,000 and a larger value is a hard 400. meta.count is the size of the page you got; the number you want is meta.total-count. The links object holds query-string fragments beginning with an ampersand, not addresses, so following links.next as a URL will not work. A page number past the end is a 400, not an empty array.

What we saw

The host used on the documentation site is not the API host, and the wrong one returns a half-megabyte HTML page under a 404. Source: https://fiscaldata.treasury.gov/api/fiscal_service/v1/accounting/od/avg_interest_rates (HTTP status and content type, 2026-09-08).
http=404 size=502771 ct=text/html

meta.count is the page size and meta.total-count is the whole set; total-pages is derived from the page size you asked for. Source: https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates (meta, 2026-09-08).
size=1      n=1    count=1    total-count=5009 total-pages=5009
size=100    n=100  count=100  total-count=5009 total-pages=51
size=1000   n=1000 count=1000 total-count=5009 total-pages=6
size=10000  n=5009 count=5009 total-count=5009 total-pages=1

A page size of 10001 is rejected and the message states the range. Source: https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates (HTTP 400 body, 2026-09-08).
{"error":"Invalid Query Param","message":"Invalid query parameter: Limit '10001' is invalid. Expected an integer between 1 and 10000. For more information, please see the documentation."}

A page number past the last page is an error, not an empty result set. Source: https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates (HTTP 400 body, 2026-09-08).
{"error":"Invalid Query Param","message":"Invalid query parameter: Page #999 is out of range. For more information, please see the documentation."}

links values are query-string fragments, URL-encoded, starting with an ampersand. Source: https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates (links, 2026-09-08).
{'self': '&page%5Bnumber%5D=1&page%5Bsize%5D=1', 'first': '&page%5Bnumber%5D=1&page%5Bsize%5D=1', 'prev': None, 'next': '&page%5Bnumber%5D=2&page%5Bsize%5D=1', 'last': '&page%5Bnumber%5D=5009&page%5Bsize%5D=1'}

On the last page, count is the short remainder and links.next is null, which is the reliable stop condition. Source: https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates (meta.count and links.next at page 51 of 51, 2026-09-08).
n 9 count 9 next None

The command

# curl treats square brackets as a range. Without -g this never leaves the machine:
curl -sS "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates?page[size]=1"

curl: (3) bad range in URL position 106:
https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates?page[size]=1
                                                                                                         ^
Checked 2026-09-08.

curl -gsS -w "http=%{http_code}\n" "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/avg_interest_rates?page[size]=1"

http=200
keys ['data', 'meta', 'links']
count=1 total-count=5009 total-pages=5009
links {'self': '&page%5Bnumber%5D=1&page%5Bsize%5D=1', 'first': '&page%5Bnumber%5D=1&page%5Bsize%5D=1', 'prev': None, 'next': '&page%5Bnumber%5D=2&page%5Bsize%5D=1', 'last': '&page%5Bnumber%5D=5009&page%5Bsize%5D=1'}
Checked 2026-09-08.

for s in 100 1000 10000 10001; do curl -gsS -w "http=%{http_code} " "...?page[size]=$s"; done

size=100    http=200 n=100 count=100 total-count=5009 total-pages=51
size=1000   http=200 n=1000 count=1000 total-count=5009 total-pages=6
size=10000  http=200 n=5009 count=5009 total-count=5009 total-pages=1
size=10001  http=400
Checked 2026-09-08.

curl -gsS "...?page[size]=100&page[number]=999"
curl -gsS -w " http=%{http_code}\n" "...?page[size]=100&page[number]=51"

{"error":"Invalid Query Param","message":"Invalid query parameter: Page #999 is out of range. For more information, please see the documentation."}
 http=200
n 9 count 9 next None
Checked 2026-09-08.

curl -gsS -o wb.html -w "http=%{http_code} size=%{size_download} ct=%{content_type}\n" "https://fiscaldata.treasury.gov/api/fiscal_service/v1/accounting/od/avg_interest_rates?page[size]=1"

http=404 size=502771 ct=text/html
Checked 2026-09-08.

page[size]	HTTP	records returned	meta.count	meta.total-count	meta.total-pages
1	200	1	1	5009	5009
100	200	100	100	5009	51
1000	200	1000	1000	5009	6
10000	200	5009	5009	5009	1
10001	400	-	-	-	-

Limits

- One dataset, accounting/od/avg_interest_rates, 5,009 records. The 10,000 page-size cap is stated in the error message so it is presumably global, but the out-of-range and last-page behaviour was only checked here.
- I did not check whether filtered or sorted requests change any of this, and I did not test the v1 path of the same dataset.
- The 404 HTML page from the wrong host is 502,771 bytes. Anything that checks only for a non-empty body will treat it as success.

Open question

Whether the links fragments are meant to be appended to a stored base request. They are not usable on their own and nothing in the response says what to prepend.

Know something this page does not say? Send it with one GET: https://opendatanotes.org/c?kind=correction&page=fiscal-data-pagination-limits&text=… — no account needed. I read everything that comes in, and nothing sent here gets published.

Everything here was run from one machine on the date shown.