query_power_retail_sales_v1

build.exascale/osint · Verify this server

Query verified U.S. annual retail electricity sales — billed MWh, revenue, and customer counts — by utility, state, and customer sector from EIA-861. Use this for "who sold how much power to whom" questions at the annual utility×state×sector grain: filter or group by `data_year`, `state`, `sector` (residential / commercial / industrial / transportation), `part`, `service_type`, `ownership`, `ba_code`, `data_type`, `eia_utility_id`, or `utility_name`. Pass filters inside the `params` object. Returns JSON aggregates with citations down to the exact stacked sector/measure cell, and optional row-level records when `include_records` is true. Defaults keep totals faithful: the in-row `total` sector block is excluded unless named explicitly (it duplicates the four sectors); EIA's state-level Adjustment (99999) and Withheld (88888) sentinel rows stay in state totals but are auto-excluded from any utility-keyed query; territories are excluded unless `included_in_default_us_metrics` is false. A result mixing service types carries a `service_type_mix` note quoting the file's own law — revenue sums Parts A,B,C,D but sales/customers sum A,B,D only (Part C delivery re-counts Part B energy). History spans data years 2016–2024, one annual census per year, each its own vintage. Reach an earlier year through `as_of`, not `data_year`: `as_of` resolves to the newest census at or before it (so `as_of` 2018-06-01 — or just 2018 — returns the 2018 census) and the response echoes that resolved `as_of`. `data_year` only filters within the resolved vintage, so `data_year` 2018 under the default `as_of` (latest = 2024) returns an empty scope, not 2018; the default serves 2024, a multi-year trend is one query per year, and an `as_of` before 2016 is refused, naming the floor. Does not determine hourly or peak load (sales are billed MWh over a year — use power.demand), facility-level or data-center-specific load, county-level detail, average retail price (cents/kWh — deferred), the ~1,700 small short-form (EIA-861S) utilities, or monthly freshness (this is the annual census, not the monthly EIA-861M sample).