Register for a free EIA API key at https://www.eia.gov/opendata/ and include it as a query parameter (?api_key=YOUR_KEY) or as an HTTP header on all requests.
Discover available Balancing Authorities by querying GET /v2/electricity/rto/fuel-type-data/facet/respondent?api_key=YOUR_KEY; the response lists all valid respondent facet values (e.g., 'CISO' for CAISO, 'ERCO' for ERCOT, 'PJM' for PJM) with descriptions.
Query hourly generation data via GET /v2/electricity/rto/fuel-type-data/data/?api_key=YOUR_KEY&frequency=hourly&data[]=value&facets[respondent][]=CISO&facets[fueltype][]=SUN&start=2025-01-01T00&end=2025-01-07T23&sort[0][column]=period&sort[0][direction]=desc; the response returns a 'response' object with a 'data' array of {period, respondent, fueltype, value, value-units} objects.
Handle pagination: the response includes 'total' and 'offset' fields; if 'total' exceeds the 'length' parameter (default 5000, max 5000), issue subsequent requests with increasing 'offset' values until all records are retrieved.
Map fuel type codes to human-readable names using the facet metadata: 'SUN'=solar, 'WND'=wind, 'NG'=natural gas, 'COL'=coal, 'NUC'=nuclear, 'OTH'=other, 'WAT'=hydropower — the full mapping is available at the /v2/electricity/rto/fuel-type-data/facet/fueltype endpoint.
For multi-BA aggregation, query each BA separately and sum by fueltype and period; the EIA does not provide a single aggregate query across multiple respondents — the respondent='US48' value covers the contiguous US total.
Known gotchas
EIA API v2 period values use ISO 8601 hour notation (e.g., '2025-01-01T00') without a colon in the time component; passing standard ISO 8601 strings with colons (e.g., '2025-01-01T00:00') will result in a 400 error — omit the colon in the hour parameter.
EIA data is published with a delay of approximately one hour for real-time estimates; the most recent hour in a query may be preliminary and revised in subsequent requests — do not treat EIA data as real-time for operational dispatch decisions.
The fuel-type-data endpoint covers electric grid operators (RTOs/ISOs) only; for utility-level generation data, use the EIA-860/923 datasets available via the bulk download portal rather than the RTO fuel-type API.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp