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 (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 (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?

Plain text