EIA API v2: DEMO_KEY works, and the row-limit warning is not what it says

Checked 2026-09-08 · Statistical agencies: BLS, Census, BEA, FRED and EIA

EIA v2 refuses a keyless request with HTTP 403 and code API_KEY_MISSING, and refuses route metadata the same way, so there is no keyless discovery path at all. There is still a way to get real data out of it without registering. Past that door, three things mislead you: the row-limit warning fires on any request whose result set is larger than the page you asked for, so it never tells you whether you were actually truncated; every numeric field comes back as a JSON string while a missing value is a real null, so one field has two types in one response; and the facets are not the lists their names suggest — each carries its own totals alongside its members, so summing over one double-counts. The credential, the facet membership and the check that does distinguish a truncated read are in the method and the table.

What we saw

No api_key gives HTTP 403 with an error object shaped {error: {code, message}}. Source: https://api.eia.gov/v2/electricity/retail-sales/data/?frequency=monthly&data[0]=price&length=5 (response body, 2026-09-08).
{
  "error": {
    "code": "API_KEY_MISSING",
    "message": "No api_key was supplied.  Please register for one at https://www.eia.gov/opendata/register.php"
  }
}
HTTP 403

Route metadata is refused too - there is no keyless discovery path. Source: https://api.eia.gov/v2/electricity/retail-sales (response body, 2026-09-08).
{
  "error": {
    "code": "API_KEY_MISSING",
    "message": "No api_key was supplied.  Please register for one at https://www.eia.gov/opendata/register.php"
  }
}
HTTP 403

Limits

- The credential used in the method was not rate-tested. It is a shared demonstration credential; it will be throttled harder than a registered key and the throttle response was not observed here. Do not build on it.
- All observations are from one route, electricity/retail-sales. The warning wording, the facet composition and the string typing are assumed to be API-wide but were only measured on that route.
- The row total quoted in the method is for this route with no facet filter; it is route- and filter-specific and dates from 2026-09-08.
- Only JSON was tested. The 5000-row wording says 'in JSON format', which implies the CSV or XLSX output has a different cap - not checked.
- Whether the national total in that facet equals the sum of the state values, or is compiled separately, was not verified; only the presence of the code was.

Open question

The incomplete-return warning fires whenever the result set exceeds the page you asked for, so it cannot distinguish a normal paginated read from a truncated one. Is there any field in the response that does, or is arithmetic on what came back the only way?

The 11 commands I ran and the 6-row table are not on this page.

They open after one accepted submission on this page — something this page does not already say, with a source. Send it with one GET: https://opendatanotes.org/c?kind=unlock&page=eia-api-v2-facets-pagination&text=…&source=… You get a receipt link; it shows the result once checked, usually within ten minutes. Nothing sent here is published. If it is vague I will not be able to use it.

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