US Electricity Prices API

Base URL & authentication

All endpoints live under one base URL. Authenticate every request with your key in the X-Api-Key header — no OAuth, no signing. The same key works on every API of the platform.

# Base URL
{{GATEWAY_URL}}

# Every request
X-Api-Key: sk_live_YOUR_KEY

Missing or invalid keys return 401 — see errors. The demo endpoint is the only keyless route.

Endpoint

One endpoint, filtered by query parameters. Every 200 ships ETag and Cache-Control; points come newest first.

Sample — 200 /electricity/retail-sales?location=texas&sector=residential&limit=2

{
  "data": [
    {
      "location": "texas",
      "location_code": "TX",
      "location_name": "Texas",
      "location_is_aggregate": false,
      "sector": "residential",
      "sector_is_aggregate": false,
      "period": "2026-05",
      "price_cents_per_kwh": 16.44,
      "sales_million_kwh": 12822.49699,
      "revenue_million_usd": 2107.48852,
      "customers": 12903067,
      "source": "Source: U.S. Energy Information Administration (August 2026)"
    }
  ],
  "meta": {
    "count": 2,
    "location": "texas",
    "location_is_aggregate": false,
    "sector": "residential",
    "frequency": "monthly",
    "next_cursor": "2026-03"
  }
}

Real response, trimmed to one point. Every numeric field is a JSON number — the upstream source returns all of them as strings.

Parameters

Pagination

Keyset by period, newest first. Ask for a page, and if there is more, meta.next_cursor carries the period to continue from; on the last page it is null.

# first page
GET /electricity/retail-sales?location=california&limit=2
# -> meta.next_cursor = "2026-03"

# next page
GET /electricity/retail-sales?location=california&limit=2&cursor=2026-03

No offsets, so a page never shifts under you when the source publishes a new month.

Errors, auth & limits

One uniform error contract: { "error": { "code", "message" }, "source" } with stable, machine-readable codes. The source attribution travels in error bodies too, and errors are never cached.

Sample — 400 ?location=texa

{
  "error": {
    "code": "UNKNOWN_LOCATION",
    "message": "Unknown location 'texa'. Use a state slug, a two-letter code, or a state name.",
    "valid_values": ["alabama", "alaska", "arizona", …]
  },
  "source": "Source: U.S. Energy Information Administration (August 2026)"
}

Typos are answered, not swallowed: the upstream source replies 200 with an empty array for a state that does not exist, which is indistinguishable from "no data yet". We validate first, so the two cases stay separate.

Data provenance

Two things about missing numbers, because they are the source's answer and not ours:

Example

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  "https://api.synergicapis.com/electricity/retail-sales?location=texas&sector=residential"

import requests

r = requests.get(
    "https://api.synergicapis.com/electricity/retail-sales",
    headers={"X-Api-Key": "sk_live_YOUR_KEY"},
    params={"location": "texas", "sector": "residential"},
)
r.raise_for_status()
latest = r.json()["data"][0]
print(latest["period"], latest["price_cents_per_kwh"], "cents/kWh")

const url = new URL("https://api.synergicapis.com/electricity/retail-sales");
url.searchParams.set("location", "texas");
url.searchParams.set("sector", "residential");

const res = await fetch(url, { headers: { "X-Api-Key": "sk_live_YOUR_KEY" } });
const { data } = await res.json();
console.log(data[0].period, data[0].price_cents_per_kwh);

Live demo

Real request against the production API — no key needed here (demo endpoint, 5 requests/minute shared across every demo on the site). Returns the US national total.

Press the button to fetch the latest official figures.

Related