Electricity Rates & Grid Mix by State — EIA Site Economics

Answers "what will power cost here, and what is the grid made of" for one or many US states, straight from the US Energy Information Administration v2 API. Built for data-center, manufacturing and industrial site selection.

Per state you get the industrial, commercial, residential and all-sector retail rate, the year-over-year change in each, the state's rate measured against the live national industrial average, and a full operating capacity rollup — by fuel, by prime mover, by balancing authority, with battery and pumped storage split out of generation, biomass counted as renewable, and planned retirements, uprates and derates flagged.

Data is first-party EIA. No scraping.

Who it's for

• Data-center and industrial site selectors — compare industrial c/kWh across a shortlist, then check whether the grid behind it is gas, wind or coal, and what is scheduled to retire.
• Energy developers and IPPs — see operating capacity by balancing authority (ERCOT vs SPP vs MISO) before siting generation or storage.
• Corporate real estate and economic development — power cost and carbon mix in one row per state.
• Analysts and AI agents — a clean, chainable per-state energy-economics record.

This is a screening tool built on EIA's published data, not an engineering study or a utility tariff quote. Retail rates are state averages across all utilities; your actual rate comes from a specific tariff.

What changed in v1.2 (2026-08-10) — read this if you stored earlier numbers

v1.1 fixed the units of what EIA publishes. v1.2 fixes the classification of it. Two corrections change numbers you may already have saved:

Defect	Effect
Hydroelectric pumped storage was counted as renewable hydro generation. EIA files it under energy source code WAT — byte-identical to a conventional dam — and the only thing that separates them is prime_mover_code = PS, which v1.1 never read.	Pumped storage is a net consumer of electricity (~80% round-trip). Nationally 21,931.2 MW was misclassified (2026-05). South Carolina's hydro_capacity_mw read 4,376.0 MW against a true 1,334.8 MW — 3.28x — and Virginia 3,912.6 against 803.3 (4.87x). Colorado read 1,187.6 against a true 679.1. Renewable share of generation: SC 23.41% → 15.73%, VA 29.91% → 24.41%. v1.1 had deliberately excluded batteries from generation while counting the grid's original battery as renewable hydro. Now in pumped_storage_capacity_mw.
Biomass was omitted from renewables entirely. EIA's own renewable definition includes wood, wood waste, landfill gas, black liquor, agricultural byproducts and other biomass; v1.1 counted only SUN/WND/WAT/GEO.	The error runs the other way — it understated biomass states. Vermont's renewable share of generation read 72.21% against a true 82.46%, Maine 49.44% against 56.28%. Nationally 9,594 MW. Now counted, and broken out as biomass_capacity_mw. Municipal solid waste is only partly biogenic and EIA does not publish the split on this route, so it is reported separately in msw_capacity_mw and deliberately not counted as renewable.

Fields affected by both: hydro_capacity_mw, renewable_capacity_mw, renewables_share_pct, renewables_share_of_generation_pct, zero_carbon_share_pct, operating_generation_capacity_mw, coal_share_pct, gas_share_pct. No field was removed or renamed.

Also in v1.2:

Change	Why
Closed vocabularies for energy_source_code (38 values) and prime_mover_code (18) are now asserted live, and an unknown value fails the run	Every fuel class the Actor publishes is keyed on that vocabulary. A code EIA adds later would be counted in the state total and appear in none of the coal / gas / nuclear / renewable / petroleum / storage figures. Nothing checked this before.
other_capacity_mw + fuel_classification_complete	Waste heat, purchased steam and "other" fit no named class. Colorado carries 6.1 MW and Texas 237.4 MW of it. Previously invisible; now reported, with a flag saying whether the named classes account for the whole state.
petroleum_capacity_mw, geothermal_capacity_mw, msw_capacity_mw	Oil-fired peaking and black-start capacity (18.2 GW nationally) had no bucket at all.
Hydrogen (H2) mapped to gas	A real, if small, EIA code that fell out of every class.
top_generation_fuel	top_fuel can legitimately answer MWH, which is storage rather than a fuel.
The retail query is now bounded to the requested history window	v1.1 sent no date bounds, so months set only the page size while response.total was the whole 2001-present series (Colorado: 1,830 rows). The completeness guard then paged all 25 years — 13 EIA requests per state to answer a 24-month question. Now one bounded request, and the window ships on the row as retail_window_start / retail_window_end.
Announced uprates and derates	EIA publishes planned-uprate-* and planned-derate-* on the same route and v1.1 requested them from nothing. A site looking for headroom cares about these as much as about retirements.
entity_id, unit, sector_id, is_storage, is_pumped_storage on plant rows	All fetched on every row since v1.0 and emitted by nothing. entity_id is the join key to EIA Form 861 and ownership data.

What changed in v1.1 (2026-08-01)

Every item below was found by re-probing the live EIA API, and each was producing a confident wrong answer on a green run:

Defect	Effect
sales_ind_mwh_latest published EIA's raw number under an MWh label	EIA publishes retail sales in million kilowatt-hours. Colorado 2026-05 read 1,259.96 "MWh" against a true 1,259,956 MWh — every sales volume was 1,000x too small. Fixed, with the raw EIA figure preserved as sales_ind_gwh_latest.
total_nameplate_capacity_mw, titled "operating", summed all four EIA generator statuses	Texas 2026-05 reported 201,329.5 MW, of which 3,922.5 MW is not operating — including 2,314.0 MW EIA marks as out of service and not expected to return. Now operating-only (197,407.0 MW), with the rest in non_operating_capacity_mw and capacity_by_status_mw.
Battery storage was treated as a fuel	EIA files batteries under energy source code MWH. Texas had 16,306.5 MW of storage sitting in the denominator of the renewables share, reporting 38.41% against a true operating-generation share of 42.54%. Storage is now split out and renewables_share_of_generation_pct added.
The rate note compared against a hard-coded 8.0 c/kWh "US average"	The live national industrial average is 8.71 c/kWh (2026-05). Colorado's 9.47 went from "well above the US average (+18%)" to "near the US average (+8.7%)" — the verdict flipped. The benchmark is now fetched live every run and published on the row.
A missing nameplate value became 0 MW	Six Colorado generators publish no net-summer capacity; those were being summed as zero. Nulls are now nulls, and capacity_rows_missing_nameplate counts them.
A capacity fetch that returned nothing produced 0 MW, 0% renewables, 0 plants	A billable row asserting the state has no power plants. Those fields are now null, with capacity_source_status: "unavailable" and partial_result: true.
An unrecognised state id returned HTTP 200 with zero rows	A typo'd state was published as a real state with no generation. Now rejected up front with state_id_recognized: false.
length=5000, no pagination, response.total never read	Texas reports total 290,133. It happened to work only because the newest month fits in one page. The capacity query now pins an explicit month and pages to completion, failing rather than emitting a fragment.
An error row was pushed per state from inside the loop	A bad key or an EIA outage produced a green run and a billable row per state carrying no data. The run now fails if no state could be read, and nothing is pushed until that gate passes.
20+ fetched columns were discarded	Operator, balancing authority, net summer/winter capacity, in-service date, planned retirement date, county and lat/lon were all in the payload and thrown away.

Live self-checks (every run, before anything is billed)

An offline fixture cannot see the upstream change, because the fixture was shaped from the upstream. Before a single row is emitted the Actor probes EIA and fails the run — emitting nothing, billing nothing — if any of these drifts:

1. Units. price must still be cents per kilowatt-hour, sales must still be million kilowatt hours, and nameplate capacity must still be MW. This is the assertion that catches the 1,000x class of bug rather than publishing it.
2. Closed retail sector vocabulary — RES, COM, IND, TRA, OTH, ALL. A new sector fails the run instead of vanishing from the price fields.
3. Closed generator status vocabulary — OP, OA, OS, SB. Capacity totals count only OP, so an unrecognised status would be silently excluded from every state total.
4. Freshness — EIA's published endPeriod must be within 8 months of today.
5. Positive canary — the national industrial benchmark must exist and land in a plausible 3–40 c/kWh band.
6. Negative control — a state id that cannot exist must match zero rows. If it matches anything, the stateid facet is not being applied and every "per state" answer is really national data.
7. Truncation guard — response.total is compared with the rows actually retrieved on every paged query.
8. Closed energy-source vocabulary — the live energy_source_code facet must contain no code outside the 38 the fuel mapping knows, and must still contain NG, SUN, WND, WAT, NUC and MWH. An unmapped code would sit in the state total and in none of the fuel classes.
9. Closed prime-mover vocabulary, and specifically that PS still exists. Conventional hydro and pumped storage share the WAT fuel code and are separated by nothing else, so if PS disappeared every hydro and renewable figure would silently re-inflate.

Checks 8 and 9 also run against the rows actually returned for each state, not only against EIA's published facet list — a code can appear in the data before it appears in the facet.

Every measured value is written to the run log.

You need a free EIA API key

Register in about a minute at https://www.eia.gov/opendata/register.php (no cost, no card) and paste it into apiKey. It is sent only to api.eia.gov.

Leaving apiKey blank falls back to this Actor's own key, which is shared across all users and throttles sooner. With no key available at all the run fails loudly with the registration URL and bills nothing — it does not return a green empty dataset.

Example input

{ "states": ["CO", "TX"], "months": 24 }

Full generator inventory for one state — every unit with operator, balancing authority, capacity, in-service date, planned retirement and coordinates:

{ "states": ["CO"], "includePlantDetail": true, "maxPlantRows": 600 }

Multi-state shortlist for a data-center search:

{ "states": ["TX", "OH", "GA", "AZ", "IA"], "months": 24 }

"US" is accepted as a state id and returns the national aggregate.

Output fields — state_profile rows

Field	Meaning
row_type	"state_profile" for the one summary row per state, or "plant" for an optional per-generator detail row.
stateid	Two-letter US state id.
state_description	Full state name as returned by EIA.
latest_period	Most recent monthly retail-rate period available (YYYY-MM).
price_res_cents_kwh	Latest-month average residential retail electricity price, cents per kWh.
price_com_cents_kwh	Latest-month average commercial retail electricity price, cents per kWh.
price_ind_cents_kwh	Latest-month average industrial retail electricity price, cents per kWh — the key figure for power-intensive site selection.
price_all_sectors_cents_kwh	Latest-month average retail electricity price across all sectors, cents per kWh.
yoy_price_change_pct_res	Percent change in residential price vs. the same calendar month one year prior. Null if the prior-year month is unavailable.
yoy_price_change_pct_com	Percent change in commercial price vs. the same calendar month one year prior.
yoy_price_change_pct_ind	Percent change in industrial price vs. the same calendar month one year prior — a key power-cost trend signal for a site.
yoy_price_change_pct_all	Percent change in all-sectors price vs. the same calendar month one year prior.
sales_ind_mwh_latest	Latest-month industrial electricity sales in MEGAWATT-HOURS. EIA publishes this series in million kilowatt-hours; v1.0 emitted the raw EIA number under an MWh label, so every value was 1,000x too small. See sales_ind_gwh_latest for the raw EIA figure.
total_nameplate_capacity_mw	Total nameplate capacity of OPERATING generators (EIA status OP) in the state for the latest available month, megawatts. Battery storage is included here and broken out separately; non-operating capacity is excluded and reported in non_operating_capacity_mw. Null means capacity was not retrieved - never 0.
capacity_by_fuel	Operating nameplate megawatts per EIA energy-source code (NG, WND, SUN, SUB, WAT, NUC, MWH...). MWH is battery/flywheel storage, not a fuel, and WAT mixes conventional hydro with pumped storage - see capacity_by_prime_mover_mw to separate them.
top_fuel	EIA energy-source code with the largest operating nameplate capacity in the state. This can legitimately answer "MWH", which is battery storage rather than a fuel; read top_generation_fuel for the largest generating fuel.
plant_count	Number of distinct plants with at least one OPERATING generator in the latest capacity month.
capacity_period	Monthly period (YYYY-MM) the capacity rollup is scoped to.
renewables_share_pct	renewable_capacity_mw as a percent of total_nameplate_capacity_mw, which includes storage. For the generation-only figure see renewables_share_of_generation_pct. CORRECTED IN v1.2 - the numerator now excludes pumped storage and includes biomass. Null when capacity was not retrieved - never 0.
industrial_rate_rank_note	Plain-English note comparing the state industrial retail rate to the LIVE US industrial average fetched from EIA in the same run (see us_avg_industrial_cents_kwh). A screening note, not a determination.
error	Error message when BOTH EIA endpoints failed for this state; null otherwise. Per-source outcomes are in retail_source_status and capacity_source_status.
checked_at	UTC timestamp of the run.
sales_ind_gwh_latest	Latest-month industrial electricity sales exactly as EIA publishes it, in million kilowatt-hours (= GWh). sales_ind_mwh_latest is this value x1000.
sales_res_mwh_latest	Latest-month residential electricity sales, converted from EIA million-kWh to megawatt-hours.
sales_com_mwh_latest	Latest-month commercial electricity sales, converted from EIA million-kWh to megawatt-hours.
sales_all_mwh_latest	Latest-month all-sectors electricity sales, converted from EIA million-kWh to megawatt-hours.
revenue_ind_musd_latest	Latest-month industrial electricity revenue in millions of dollars, as published by EIA.
customers_ind_latest	Number of industrial retail customers in the latest month.
customers_all_latest	Number of retail customers across all sectors in the latest month.
price_period_res	Month (YYYY-MM) the residential price is from. Sectors can publish at different lags.
price_period_com	Month (YYYY-MM) the commercial price is from.
price_period_ind	Month (YYYY-MM) the industrial price is from.
price_period_all	Month (YYYY-MM) the all-sectors price is from.
price_tra_cents_kwh	Latest-month average transportation-sector retail price, cents per kWh.
us_avg_industrial_cents_kwh	The national industrial retail rate the rate note is written against, fetched live from EIA (stateid=US, sectorid=IND).
us_avg_industrial_period	Month (YYYY-MM) of the national industrial benchmark.
us_benchmark_source	Always "eia_live" on an emitted row: the national industrial benchmark is fetched from EIA (stateid=US, sectorid=IND) in the pre-flight, and a run that cannot retrieve it fails before any row is emitted or billed rather than falling back to a pinned constant.
industrial_rate_vs_us_pct	Percent by which this state industrial rate is above (+) or below (-) the national industrial average.
operating_generation_capacity_mw	Operating nameplate capacity EXCLUDING all storage - battery/flywheel (energy source MWH) and hydroelectric pumped storage (prime mover PS). This is capacity that actually generates electricity. CORRECTED IN v1.2 - v1.1 excluded batteries but counted 21,931.2 MW of national pumped storage as generation.
battery_storage_capacity_mw	Operating nameplate capacity filed under energy source code MWH - batteries and flywheels. Does NOT include hydroelectric pumped storage; see pumped_storage_capacity_mw and total_storage_capacity_mw.
non_operating_capacity_mw	Nameplate capacity in the state with a status other than OP (out of service or standby). Reported separately and EXCLUDED from the operating totals.
capacity_by_status_mw	Nameplate megawatts per EIA generator status code: OP Operating, OA out of service but expected back, OS out of service and not expected back, SB standby/backup.
net_summer_capacity_mw	Sum of operating generators net summer capacity - the figure that matters for summer peak. Null when EIA publishes none.
net_winter_capacity_mw	Sum of operating generators net winter capacity.
generator_count	Number of generator records in the latest capacity period, all statuses.
nuclear_capacity_mw	Operating nameplate capacity with energy source code NUC.
coal_capacity_mw	Operating nameplate capacity across coal energy source codes (BIT, SUB, LIG, ANT, RC, WC, SGC).
gas_capacity_mw	Operating nameplate capacity across gas energy-source codes NG, BFG, OG, PG, SGP and H2 (hydrogen, added to the mapping in v1.2).
solar_capacity_mw	Operating nameplate capacity with energy source code SUN.
wind_capacity_mw	Operating nameplate capacity with energy source code WND.
hydro_capacity_mw	CONVENTIONAL hydroelectric operating nameplate capacity: energy source code WAT with a prime mover other than PS. CORRECTED IN v1.2 - v1.1 counted every WAT generator, which folded hydroelectric PUMPED STORAGE into hydro. South Carolina read 4,376.0 MW against a true 1,334.8 MW (3.28x) and Virginia 3,912.6 against 803.3 (4.87x). Pumped storage is now reported separately in pumped_storage_capacity_mw. If you stored this number before 2026-08-10 it is too high wherever the state has pumped storage.
renewable_capacity_mw	Renewable operating nameplate capacity: solar (SUN) + wind (WND) + conventional hydro (WAT excluding prime mover PS) + geothermal (GEO) + biomass (WDS, WDL, OBS, OBL, OBG, BLQ, AB, SLW, LFG). CORRECTED IN v1.2 in two directions - v1.1 counted pumped storage as renewable hydro AND omitted biomass entirely. Municipal solid waste is only partly biogenic and EIA does not publish the split here, so it is reported separately in msw_capacity_mw and is NOT counted as renewable.
renewables_share_of_generation_pct	renewable_capacity_mw as a percent of operating_generation_capacity_mw (storage excluded from both sides). CORRECTED IN v1.2: South Carolina reads 15.73% against v1.1's 23.41%, Virginia 24.41% against 29.91% (pumped storage removed), while Vermont reads 82.46% against 72.21% and Maine 56.28% against 49.44% (biomass added).
zero_carbon_share_pct	Renewable plus nuclear capacity as a percent of operating_generation_capacity_mw. Follows the v1.2 renewable correction (pumped storage out, biomass in).
coal_share_pct	Coal capacity as a percent of operating_generation_capacity_mw. The denominator changed in v1.2 when pumped storage was reclassified as storage.
gas_share_pct	Gas capacity as a percent of operating_generation_capacity_mw. The denominator changed in v1.2 when pumped storage was reclassified as storage. Hydrogen (H2) is counted here.
capacity_by_balancing_authority_mw	Operating nameplate megawatts per balancing authority (ERCO, MISO, SWPP, PSCO, ...). The grid a site would actually interconnect to.
top_balancing_authority	Balancing authority holding the largest share of the state operating capacity.
planned_retirement_capacity_mw	Operating nameplate capacity that EIA records a planned retirement date for. Null when no generator carries one.
planned_retirement_generator_count	Number of operating generators carrying a planned retirement date.
next_planned_retirement_period	Earliest FUTURE planned retirement year-month among operating generators in the state, relative to the capacity month. Dates EIA files in the past are excluded and counted in planned_retirement_dates_before_period.
retail_source_status	Per-source outcome for the EIA retail-sales endpoint on this row: ok, empty, unknown_state, or unavailable. Null price fields under "unavailable" mean NOT CHECKED, not zero.
capacity_source_status	Per-source outcome for the EIA generator-capacity endpoint: ok, empty, unknown_state, or unavailable.
us_benchmark_status	Whether the national industrial benchmark was retrieved this run. Always "ok" on an emitted row - the run fails if it was not.
state_id_recognized	False when the supplied state id is not one EIA publishes - a typo returns HTTP 200 with zero rows, which would otherwise look like a state with no power plants.
partial_result	True when any contributing source was degraded, so no field on this row should be read as a verified negative.
retail_rows_total	Rows EIA reports as matching the retail-sales query (response.total). From v1.2 the query is bounded to the requested history window, so this is the row count for that window rather than the whole 2001-present series.
retail_rows_fetched	Number of retail-sales rows actually retrieved. Equal to retail_rows_total on a complete fetch.
capacity_rows_total	Number of generator rows EIA reports for the pinned capacity month, from response.total.
capacity_rows_fetched	Number of generator rows actually retrieved. The run fails rather than emit a fragment if these disagree.
capacity_rows_missing_nameplate	How many generator rows EIA published with no nameplate capacity. Those rows contribute nothing to the totals rather than being counted as 0 MW.
generator_id	EIA generator id within the plant.
energy_source_description	EIA plain-text description of the energy source code.
prime_mover_code	EIA prime mover code (GT, CT, CA, ST, WT, PV, BA, ...).
net_summer_mw	Generator net summer capacity in megawatts. Null when EIA publishes none - never 0.
net_winter_mw	Generator net winter capacity in megawatts.
status	EIA generator status code: OP, OA, OS or SB.
status_description	Plain-text EIA status description.
entity_name	Utility or independent power producer that operates the generator.
sector_name	EIA sector of the operating entity (Electric Utility, IPP Non-CHP, ...).
balancing_authority_code	Balancing authority the generator sits in (ERCO, MISO, SWPP, PSCO, ...).
balancing_authority_name	Plain-text balancing authority name.
operating_year_month	Year-month the generator entered service.
planned_retirement_year_month	Year-month EIA records as the planned retirement. Null when none is filed.
county	County the plant is in.
latitude	Plant latitude, WGS84 decimal degrees.
longitude	Plant longitude, WGS84 decimal degrees.
period	Capacity month (YYYY-MM) the plant row is scoped to.
planned_retirement_dates_before_period	How many operating generators carry a planned-retirement date EARLIER than the capacity month. EIA files a few in-service dates into that column (Texas 2026-05: Jones units 3 and 4 at 1956-12 and 1958-12), so they are counted here and excluded from next_planned_retirement_period rather than publishing a retirement date in 1956.
pumped_storage_capacity_mw	Operating nameplate capacity of hydroelectric PUMPED STORAGE - energy source WAT with prime mover PS. A net consumer of electricity (about 80% round-trip), so it is excluded from hydro, renewable and generation totals. 21,931.2 MW nationally in 2026-05.
total_storage_capacity_mw	All operating storage: battery_storage_capacity_mw plus pumped_storage_capacity_mw.
biomass_capacity_mw	Operating nameplate capacity across the biomass energy-source codes WDS, WDL, OBS, OBL, OBG, BLQ, AB, SLW and LFG. Counted inside renewable_capacity_mw from v1.2; v1.1 omitted it entirely.
msw_capacity_mw	Operating nameplate capacity with energy source code MSW. Reported on its own line and deliberately NOT counted as renewable: only part of MSW is biogenic and EIA does not publish the split in this dataset.
geothermal_capacity_mw	Operating nameplate capacity with energy source code GEO. Counted inside renewable_capacity_mw.
petroleum_capacity_mw	Operating nameplate capacity across DFO, RFO, KER, JF, PC, WO and TDF - mostly oil-fired peaking and black-start units.
other_capacity_mw	Operating megawatts that fall into none of the named classes (for example waste heat WH, purchased steam PUR, other OTH, or a row with no energy source code). Should be small; a large value means the fuel mapping no longer covers the state.
fuel_classification_complete	True when every operating megawatt in the state landed in a named fuel class (other_capacity_mw is zero). False means part of the state total is unclassified.
capacity_by_prime_mover_mw	Operating nameplate megawatts per EIA prime-mover code (ST, CT, GT, WT, PV, CA, HY, BA, PS, ...). This is what separates conventional hydro (HY) from pumped storage (PS) and batteries (BA) from flywheels (FW).
top_generation_fuel	EIA energy-source code with the largest operating nameplate capacity once storage (MWH) is excluded - the fuel a site would actually be buying from.
operating_generator_count	Number of generator records with status OP in the latest capacity period. generator_count counts all statuses.
storage_share_of_operating_capacity_pct	total_storage_capacity_mw as a percent of total_nameplate_capacity_mw.
petroleum_share_pct	petroleum_capacity_mw as a percent of operating_generation_capacity_mw.
planned_uprate_capacity_mw	Sum of planned-uprate summer capacity across operating generators that have an announced uprate. Null when no operating generator in the state publishes one.
planned_uprate_generator_count	Operating generators with an announced uprate date.
next_planned_uprate_period	Earliest announced uprate month among operating generators in the state.
planned_derate_capacity_mw	Sum of planned-derate summer capacity across operating generators that have an announced derate. Null when no operating generator in the state publishes one.
planned_derate_generator_count	Operating generators with an announced derate date.
next_planned_derate_period	Earliest announced derate month among operating generators in the state.
capacity_rows_missing_fuel_code	Generator rows EIA published with no energy_source_code. Their megawatts are in the state total and in other_capacity_mw, not in any fuel class.
retail_window_start	First month of the bounded retail-sales query, derived from the "months" input and EIA's published endPeriod.
retail_window_end	Last month of the bounded retail-sales query - EIA's published endPeriod for retail sales.

Output fields — plant rows (includePlantDetail: true)

Set includePlantDetail: true to also get one billable row per generator.

Field	Meaning
plantid	EIA plant id. Present only on row_type "plant" rows.
plant_name	Generating plant name. Present only on row_type "plant" rows.
fuel	EIA energy-source code for the generator. Present only on row_type "plant" rows.
technology	Generator technology description. Present only on row_type "plant" rows.
nameplate_mw	Generator nameplate capacity in megawatts. Null when EIA publishes no value - never 0.
is_storage	True when the generator is a storage device rather than a generator: energy source MWH (battery/flywheel) or prime mover PS (pumped storage). Present only on row_type "plant" rows.
is_pumped_storage	True when the generator is hydroelectric pumped storage (WAT + prime mover PS). Present only on row_type "plant" rows.
entity_id	EIA entity (utility/operator) id - the join key to EIA Form 861 and ownership data. Fetched on every row since v1.0 and emitted from v1.2. Present only on row_type "plant" rows.
unit	Generator unit designation as EIA publishes it. Present only on row_type "plant" rows.
sector_id	Machine-readable EIA sector id (electric-utility, ipp-non-chp, industrial-chp, ...). Present only on row_type "plant" rows.
planned_uprate_year_month	Announced uprate month for this generator, YYYY-MM. Present only on row_type "plant" rows.
planned_uprate_summer_cap_mw	Summer capacity this generator is planned to reach. Present only on row_type "plant" rows.
planned_derate_year_month	Announced derate month for this generator, YYYY-MM. Present only on row_type "plant" rows.
planned_derate_summer_cap_mw	Summer capacity this generator is planned to fall to. Present only on row_type "plant" rows.

Field coverage (verified live, full dataset, 2026-08-10)

Audited on the complete dataset of a healthy run using the Actor's own prefill (states: ["CO","TX"]), not a sample:

• The state_profile prefill run populates every declared summary field except the ones that are structurally conditional: error (null on success — good news) and the *_source_status values that only read anything other than ok when a source is degraded.
• planned_retirement_capacity_mw / next_planned_retirement_period are null for a state where EIA files no retirement dates; Colorado 2026-05 has 26 generators carrying one, so {"states":["CO"]} populates them.
• planned_uprate_* / planned_derate_* are EIA's own columns, not derived values, so a null means EIA published nothing — never 0 MW. The prefill populates both: Colorado carries 1 announced uprate (0.3 MW, 2027-10) and Texas the only announced derate in the country on 2026-05 data (Coleto Creek, 28 MW, 2026-12). {"states":["SC"]} is the densest uprate case — 23 generators, 222 MW.
• pumped_storage_capacity_mw reads a measured 0 in a state with no pumped storage (Texas, Vermont) and 508.5 MW in Colorado; {"states":["SC","VA"]} shows the largest values in the country (3,041.2 and 3,109.3 MW).
• msw_capacity_mw and geothermal_capacity_mw are a measured 0 in the prefill states. {"states":["NY","FL","MN"]} populates MSW; {"states":["CA","NV","HI"]} populates geothermal.
• other_capacity_mw / fuel_classification_complete: Colorado carries 6.1 MW of waste heat and Texas 237.4 MW of waste heat plus purchased steam, so both prefill states report fuel_classification_complete: false with the residual named. South Carolina and Vermont report true and 0.
• plant rows only exist when includePlantDetail: true. {"states":["SC"],"includePlantDetail":true,"maxPlantRows":400} is the recorded input that populates is_pumped_storage: true (16 of 395 generators — Jocassee, Bad Creek) and the uprate columns.
• unit is the one plant column EIA populates sparsely — 2,150 of 25,868 operating generators nationally (8.3%), concentrated in TX, CA, FL, NY and PA. {"states":["TX"],"includePlantDetail":true} is the recorded input that populates it. Null there means EIA files no unit designation, not that the generator has none.
• net_summer_mw is null on the handful of generators EIA publishes no net-summer value for — 6 of 508 in Colorado. That is "EIA has not published it", never 0 MW.

Pricing

Pay-per-result: $8.00 per 1,000 results on the free tier, with graduated paid-plan discounts (Bronze −20%, Silver −30%, Gold −45%, Platinum −60%, Diamond −70%). One state_profile row per state; per-generator rows are billed individually and are off by default. A run that fails a drift check, or that cannot read EIA for any requested state, emits nothing and bills nothing.

Use as an MCP tool

Callable by AI agents via mcp.apify.com. Every output field is described in the schema, including the per-source status fields — so an agent can tell the difference between "this state has no coal" and "capacity was not retrieved", which is the distinction that makes an energy answer safe to act on.

FAQ

Where does the data come from? The EIA v2 API: electricity/retail-sales for rates and electricity/operating-generator-capacity for the generation fleet. Both are first-party US government data.

Is total_nameplate_capacity_mw the same as what the state can actually generate? No. It is nameplate capacity of operating units, which is the plate rating. net_summer_capacity_mw is closer to what is dispatchable on a hot afternoon, and neither accounts for outages or fuel availability.

Why is battery storage reported separately? Because it is not generation. EIA files it under energy source code MWH; including it in a renewables share inflates the denominator and understates the answer.

What does a null mean? Not checked. A 0 means checked and genuinely zero. Every row carries retail_source_status, capacity_source_status and partial_result so the two are never confused.

How current is it? EIA publishes retail sales and generator capacity with roughly a two-month lag; latest_period and capacity_period state exactly which month each figure is from, and the run fails if the feed goes more than 8 months stale.

Can I get every generator in a state? Yes — includePlantDetail: true. Each row is billable, so maxPlantRows caps it. Colorado has ~508 generators in a month, Texas ~2,451.

Related Actors

• Interconnection Queue Tracker — what is waiting to connect to the grid you just priced.
• HIFLD Grid Proximity Screener — distance from a specific coordinate to the nearest transmission line and substation.
• EPA Nonattainment Air Permit Screener — whether a thermal plant or generator at that site faces a stricter permitting threshold.