API v1 docs

Public read API

LoadConsensus API v1

Programmatic access to US power forecasts and datacenter pipeline. JSON over HTTPS, bearer-token auth, predictable per-key daily quotas.

Clients & SDKs

Official clients are first-class — they use the same bearer auth, observe the same per-key daily rate limits, and return the same response shapes as the raw REST API. Versioning tracks the API version (v1).

TypeScript

npm install @loadconsensus/sdk

import { LoadConsensusClient } from '@loadconsensus/sdk';

const client = new LoadConsensusClient({ apiKey: process.env.LC_API_KEY! });

const { data } = await client.consensus({
  isoRegion: 'ERCOT',
  metric: 'peak-demand-gw',
  targetYear: 2030,
});

console.log(data.median, data.unit, `(${data.sourceCount} sources)`);
// client.rateLimit -> { limit, remaining, reset }

Python

pip install loadconsensus

from loadconsensus import Client

client = Client(api_key="lc_...")

result = client.consensus(iso_region="ERCOT", metric="peak-demand-gw", target_year=2030)
data = result["data"]
print(data["median"], data["unit"], f"({data['sourceCount']} sources)")
# client.rate_limit -> RateLimit(limit=..., remaining=..., reset=...)

Source for both clients lives in the monorepo at github.com/001Sir/loadconsensus/tree/main/sdks.

Authentication

Every endpoint except /health requires an Authorization: Bearer lc_<key> header. Keys are issued at Pro tier and above — see pricing to subscribe. Keys are shown once at creation; we store only a sha-256 hash.

curl -H "Authorization: Bearer lc_..." https://loadconsensus.com/api/v1/sources

In local development with NODE_ENV !== "production", requests without the header fall through to a dev bypass capped at 100 calls/day. This bypass is never active in production.

Rate limits

Tier	Daily quota
Pro	1,000 / day
Team	50,000 / day
Enterprise	Custom

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (UTC seconds). Quotas reset at UTC midnight.

Endpoints

GET/api/v1/health

Liveness probe. Public — no Authorization header required. Use for uptime monitoring.

Query parameters

No parameters.

Example request

curl https://loadconsensus.com/api/v1/health

Example response

{
  "ok": true,
  "timestamp": "2026-05-15T12:00:00.000Z",
  "version": "v1.0.0"
}

GET/api/v1/sources

List active forecast publishers. Filter by category (federal | rto | state-puc | commercial) or isoRegion.

Query parameters

Param	Type	Description
category	string	federal \| rto \| state-puc \| commercial
isoRegion	string	ERCOT \| PJM \| MISO \| CAISO \| ISO-NE \| NYISO \| SPP \| NATIONAL

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/sources?category=federal"

Example response

{
  "data": [
    {
      "id": "eia-aeo",
      "name": "EIA Annual Energy Outlook",
      "category": "federal",
      "isoRegion": "NATIONAL",
      "baseUrl": "https://www.eia.gov/outlooks/aeo/",
      "releaseSchedule": "Annual, April"
    },
    {
      "id": "eia-steo",
      "name": "EIA Short-Term Energy Outlook",
      "category": "federal",
      "isoRegion": "NATIONAL",
      "baseUrl": "https://www.eia.gov/outlooks/steo/",
      "releaseSchedule": "Monthly, 2nd Tuesday"
    }
  ],
  "meta": { "count": 2 }
}

GET/api/v1/load-forecasts

List the latest forecast rows. Each row is one (source × ISO × metric × year) tuple. Default page size 100, max 500.

Query parameters

Param	Type	Description
isoRegion	string	ERCOT \| PJM \| MISO \| CAISO \| ISO-NE \| NYISO \| SPP \| NATIONAL
metric	string	peak-demand-gw \| annual-energy-twh \| annual-generation-twh \| net-load-gw \| load-growth-pct
targetYear	integer	Forecast horizon year (e.g. 2026, 2030)
sourceId	string	Restrict to a single publisher (e.g. eia-steo)
limit	integer	Page size. Default 100, max 500.

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/load-forecasts?isoRegion=CAISO&metric=annual-energy-twh&targetYear=2026"

Example response

{
  "data": [
    {
      "id": "lf_13e2334bf2634bb9e8c6fdb0",
      "sourceId": "eia-steo",
      "documentId": null,
      "isoRegion": "CAISO",
      "metric": "annual-energy-twh",
      "targetYear": 2026,
      "targetSeason": null,
      "value": 253.59537472,
      "unit": "TWh",
      "scenarioLabel": "reference",
      "notes": null,
      "fetchedAt": "2026-05-14T00:00:00.000Z"
    },
    {
      "id": "lf_nerc_caiso_energy_2026",
      "sourceId": "nerc-ltra",
      "documentId": null,
      "isoRegion": "CAISO",
      "metric": "annual-energy-twh",
      "targetYear": 2026,
      "targetSeason": null,
      "value": 266,
      "unit": "TWh",
      "scenarioLabel": "reference",
      "notes": null,
      "fetchedAt": "2026-05-14T00:00:00.000Z"
    }
  ],
  "meta": { "count": 2, "sources": ["eia-steo", "nerc-ltra"] }
}

GET/api/v1/consensus

Cross-source consensus (min / median / max) for a single (isoRegion, metric, targetYear) tuple. Returns 404 when no rows match.

Query parameters

Param	Type	Description
isoRegion*	string	e.g. CAISO
metric*	string	e.g. annual-energy-twh
targetYear*	integer	e.g. 2026

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/consensus?isoRegion=CAISO&metric=annual-energy-twh&targetYear=2026"

Example response

{
  "data": {
    "isoRegion": "CAISO",
    "metric": "annual-energy-twh",
    "targetYear": 2026,
    "unit": "TWh",
    "min": 253.59537472,
    "max": 266,
    "median": 259.79768736,
    "sourceCount": 2,
    "values": [
      { "sourceId": "eia-steo", "value": 253.59537472 },
      { "sourceId": "nerc-ltra", "value": 266 }
    ]
  }
}

GET/api/v1/datacenter-projects

List tracked datacenter projects, sorted by the larger of operatingMw / announcedMw. Filter by ISO, state, status, or operator.

Query parameters

Param	Type	Description
isoRegion	string	ERCOT \| PJM \| MISO \| ...
state	string	Two-letter US state code (e.g. VA, TX)
status	string	announced \| permitted \| under-construction \| operating \| cancelled
operator	string	e.g. Amazon, Meta, Microsoft

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/datacenter-projects?status=operating"

Example response

{
  "data": [
    {
      "id": "dcp_amazon_ashburn",
      "slug": "amazon-ashburn-va",
      "name": "AWS US-East-1 Ashburn Campus",
      "operator": "Amazon",
      "utilityId": null,
      "isoRegion": "PJM",
      "state": "VA",
      "county": "Loudoun",
      "city": "Ashburn",
      "lat": 39.0438,
      "lng": -77.4874,
      "announcedMw": null,
      "operatingMw": 2500,
      "status": "operating",
      "announcedDate": null,
      "operationalDate": "2020-01-01",
      "sourceUrl": null,
      "sourceNotes": null,
      "sources": [],
      "createdAt": "2026-05-14T00:00:00.000Z",
      "updatedAt": "2026-05-14T00:00:00.000Z"
    }
  ],
  "meta": { "count": 1, "totalAnnouncedMw": 0, "totalOperatingMw": 2500 }
}

GET/api/v1/datacenter-projects/{slug}

Fetch a single datacenter project by slug. 404 when no match.

Query parameters

Param	Type	Description
slug*	string	Path segment, e.g. amazon-ashburn-va

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/datacenter-projects/meta-richland-parish-la"

Example response

{
  "data": {
    "id": "dcp_meta_richland",
    "slug": "meta-richland-parish-la",
    "name": "Meta Richland Parish Hyperion",
    "operator": "Meta",
    "utilityId": null,
    "isoRegion": "MISO",
    "state": "LA",
    "county": "Richland Parish",
    "city": null,
    "lat": null,
    "lng": null,
    "announcedMw": 2000,
    "operatingMw": null,
    "status": "announced",
    "announcedDate": "2024-12-04",
    "operationalDate": null,
    "sourceUrl": null,
    "sourceNotes": null,
    "sources": [],
    "createdAt": "2026-05-14T00:00:00.000Z",
    "updatedAt": "2026-05-14T00:00:00.000Z"
  }
}

GET/api/v1/power-events

Upcoming forecast-release calendar events. Defaults to a 90-day window from today. Filter by ISO.

Query parameters

Param	Type	Description
isoRegion	string	e.g. PJM
from	ISO date	Inclusive lower bound. Defaults to today (UTC).
to	ISO date	Inclusive upper bound. Defaults to 90 days after `from`.

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/power-events?isoRegion=PJM"

Example response

{
  "data": [
    {
      "id": "pe_jan_pjm_load_2026",
      "source": "pjm-load-forecast",
      "externalId": null,
      "eventName": "PJM Load Forecast Report 2026",
      "isoRegion": "PJM",
      "category": "forecast-release",
      "date": "2026-01-30T16:00:00.000Z",
      "description": null,
      "url": "https://www.pjm.com/library/reports-notices/load-forecast-report.aspx"
    }
  ],
  "meta": {
    "count": 1,
    "from": "2026-05-15T00:00:00.000Z",
    "to": "2026-08-13T00:00:00.000Z"
  }
}

CSV exports

Pro+ tier. Each CSV route mirrors the query parameters of its JSON sibling and adds standard download headers (text/csv; charset=utf-8, Content-Disposition: attachment). A Authorization: Bearer lc_... header is required — Free-tier keys and the local dev bypass receive a 402 upgrade_required response so the tier gate is validated end-to-end.

Per-tier row caps: Pro 50,000, Team 200,000, Enterprise 1,000,000. Files are returned in a single response — no pagination cursors.

curl -H "Authorization: Bearer lc_abc..." \
  "https://loadconsensus.com/api/v1/load-forecasts.csv?isoRegion=ERCOT&metric=annual-energy-twh" \
  -o ercot-forecasts.csv

GET/api/v1/load-forecasts.csv

Latest forecast rows as CSV. Same filters as the JSON sibling. Per-tier row caps: Pro 50K, Team 200K, Enterprise 1M.

Filename

load-forecasts-YYYYMMDD.csv

Columns

id, sourceId, isoRegion, metric, targetYear, targetSeason, value, unit, scenarioLabel, isLatest, fetchedAt

Query parameters

Param	Type	Description
isoRegion	string	ERCOT \| PJM \| MISO \| CAISO \| ISO-NE \| NYISO \| SPP \| NATIONAL
metric	string	peak-demand-gw \| annual-energy-twh \| ...
targetYear	integer	Forecast horizon year.
sourceId	string	Restrict to a single publisher.

GET/api/v1/datacenter-projects.csv

Datacenter pipeline as CSV. Excludes the JSONB `sources` array and long-text `sourceNotes` by default; add `?include=sources,notes` to opt in (rendered as JSON-stringified cells).

Filename

datacenter-projects-YYYYMMDD.csv

Columns

id, slug, name, operator, utilityId, isoRegion, state, city, lat, lng, announcedMw, operatingMw, status, announcedDate, sourceUrl

Query parameters

Param	Type	Description
isoRegion	string	ERCOT \| PJM \| MISO \| ...
state	string	Two-letter US state code.
status	string	announced \| permitted \| under-construction \| operating \| cancelled
operator	string	e.g. Amazon, Meta, Microsoft
include	string	Comma list: `sources`, `notes`.

GET/api/v1/revisions.csv

Forecast revision history. Filter by `since` (ISO date) and `minAbsPct` (only rows where |deltaPct| ≥ N). Same Pro/Team/Enterprise row caps as load-forecasts.csv.

Filename

forecast-revisions-YYYYMMDD.csv

Columns

id, forecastId, sourceId, isoRegion, metric, targetYear, priorValue, deltaAbsolute, deltaPct, recordedAt

Query parameters

Param	Type	Description
since	ISO date	Inclusive lower bound on recordedAt.
minAbsPct	number	Drop rows where \|deltaPct\| < this value.

Webhooks

Pro+ tier. Configure an https URL at /account/webhooks and receive signed HTTP POSTs when matching events occur. Each subscription has a dedicated signing secret; you verify payloads by recomputing the HMAC-SHA256 over the raw request body.

Event types

Type	Fires when
forecast.revision	A LoadForecast row was updated — payload includes priorValue, newValue, deltaAbsolute, deltaPct, isoRegion, metric, targetYear.
dc.announcement	A new DatacenterProject row was created, or a tracked field changed (operator, status, announcedMw, operatingMw).
jobrun.failure	A cron worker recorded status='failed' in JobRun. Payload includes jobName, fail count, errorSample.

Filters

Each subscription accepts an isoFilters allowlist (empty = all regions) and an optional minDeltaPct floor — forecast.revision events with abs(deltaPct) < minDeltaPct are skipped.

Payload envelope

{
  "id": "whd_<hex>",
  "type": "forecast.revision",
  "createdAt": "2026-05-15T12:00:00.000Z",
  "data": {
    "revisionId": "...",
    "forecastId": "lf_...",
    "sourceId": "eia-steo",
    "isoRegion": "ERCOT",
    "metric": "annual-energy-twh",
    "targetYear": 2026,
    "priorValue": 482.1,
    "newValue": 491.7,
    "unit": "TWh",
    "deltaAbsolute": 9.6,
    "deltaPct": 1.99,
    "recordedAt": "2026-05-15T11:59:42.000Z"
  }
}

Headers

Header	Value
X-LoadConsensus-Signature	sha256=<hex of HMAC-SHA256(secret, raw_body)>
X-LoadConsensus-Event	e.g. forecast.revision
X-LoadConsensus-Delivery	whd_<hex> — unique per attempt

Verifying signatures

Compute the same HMAC over the raw request body and constant-time compare against the header value (strip the sha256= prefix). Reject on mismatch before parsing JSON.

curl + bash

# Receiver side — verify and respond.
# RAW_BODY must be the exact bytes from the request (do not re-serialize).
SECRET="whsec_..."
SIG_HEADER="$HTTP_X_LOADCONSENSUS_SIGNATURE"  # e.g. "sha256=abc123..."
RAW_BODY="$(cat)"

expected="sha256=$(printf '%s' "$RAW_BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" \
  | awk '{print $2}')"

if [ "$expected" = "$SIG_HEADER" ]; then
  echo "OK"; exit 0
else
  echo "signature mismatch"; exit 1
fi

node

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody: string, header: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Delivery + retry policy

At-most-once. No automatic retry.
10-second timeout per POST.
2xx = success. Any non-2xx, network error, or timeout = failure.
Each attempt is recorded in the delivery log at /account/webhooks with response status, latency, and body (first 500 chars).
After 10 consecutive failures the subscription is auto-disabled (isActive=false). Re-enable by creating a new subscription.
Use the per-subscription Test fire button to send a synthetic event end-to-end before relying on the production fan-out.

Errors

All error responses use the shape { error, hint? }. The HTTP status is the source of truth.

401Missing or invalid Authorization header.

{ "error": "unauthorized", "hint": "Include Authorization: Bearer lc_... header" }

402CSV endpoint requested with a Free-tier key (or the local dev bypass). Upgrade to Pro+.

{ "error": "upgrade_required", "hint": "CSV export requires Pro or higher" }

404No row matches the requested slug or (iso, metric, year) tuple.

{ "error": "not_found", "hint": "No forecasts for ERCOT / peak-demand-gw / 2099" }

429Per-key daily quota exhausted. Resets at UTC midnight.

{ "error": "rate_limit_exceeded", "remaining": 0, "reset": 1747353600 }

500Unexpected server error. Safe to retry with backoff.

{ "error": "server_error" }

Changelog

v1.0.02026-05-15
- Initial release.
- Endpoints: /health, /sources, /load-forecasts, /consensus, /datacenter-projects, /datacenter-projects/{slug}, /power-events.
- Bearer-token auth via the ApiKey table. Per-key daily rate limit. X-RateLimit-* headers on every response.

API v1 docs

Public read API

LoadConsensus API v1

Programmatic access to US power forecasts and datacenter pipeline. JSON over HTTPS, bearer-token auth, predictable per-key daily quotas.

Clients & SDKs

TypeScript

npm install @loadconsensus/sdk

import { LoadConsensusClient } from '@loadconsensus/sdk';

const client = new LoadConsensusClient({ apiKey: process.env.LC_API_KEY! });

const { data } = await client.consensus({
  isoRegion: 'ERCOT',
  metric: 'peak-demand-gw',
  targetYear: 2030,
});

console.log(data.median, data.unit, `(${data.sourceCount} sources)`);
// client.rateLimit -> { limit, remaining, reset }

Python

pip install loadconsensus

from loadconsensus import Client

client = Client(api_key="lc_...")

result = client.consensus(iso_region="ERCOT", metric="peak-demand-gw", target_year=2030)
data = result["data"]
print(data["median"], data["unit"], f"({data['sourceCount']} sources)")
# client.rate_limit -> RateLimit(limit=..., remaining=..., reset=...)

Source for both clients lives in the monorepo at github.com/001Sir/loadconsensus/tree/main/sdks.

Authentication

curl -H "Authorization: Bearer lc_..." https://loadconsensus.com/api/v1/sources

In local development with NODE_ENV !== "production", requests without the header fall through to a dev bypass capped at 100 calls/day. This bypass is never active in production.

Rate limits

Tier	Daily quota
Pro	1,000 / day
Team	50,000 / day
Enterprise	Custom

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (UTC seconds). Quotas reset at UTC midnight.

Endpoints

GET/api/v1/health

Liveness probe. Public — no Authorization header required. Use for uptime monitoring.

Query parameters

No parameters.

Example request

curl https://loadconsensus.com/api/v1/health

Example response

{
  "ok": true,
  "timestamp": "2026-05-15T12:00:00.000Z",
  "version": "v1.0.0"
}

GET/api/v1/sources

List active forecast publishers. Filter by category (federal | rto | state-puc | commercial) or isoRegion.

Query parameters

Param	Type	Description
category	string	federal \| rto \| state-puc \| commercial
isoRegion	string	ERCOT \| PJM \| MISO \| CAISO \| ISO-NE \| NYISO \| SPP \| NATIONAL

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/sources?category=federal"

Example response

{
  "data": [
    {
      "id": "eia-aeo",
      "name": "EIA Annual Energy Outlook",
      "category": "federal",
      "isoRegion": "NATIONAL",
      "baseUrl": "https://www.eia.gov/outlooks/aeo/",
      "releaseSchedule": "Annual, April"
    },
    {
      "id": "eia-steo",
      "name": "EIA Short-Term Energy Outlook",
      "category": "federal",
      "isoRegion": "NATIONAL",
      "baseUrl": "https://www.eia.gov/outlooks/steo/",
      "releaseSchedule": "Monthly, 2nd Tuesday"
    }
  ],
  "meta": { "count": 2 }
}

GET/api/v1/load-forecasts

List the latest forecast rows. Each row is one (source × ISO × metric × year) tuple. Default page size 100, max 500.

Query parameters

Param	Type	Description
isoRegion	string	ERCOT \| PJM \| MISO \| CAISO \| ISO-NE \| NYISO \| SPP \| NATIONAL
metric	string	peak-demand-gw \| annual-energy-twh \| annual-generation-twh \| net-load-gw \| load-growth-pct
targetYear	integer	Forecast horizon year (e.g. 2026, 2030)
sourceId	string	Restrict to a single publisher (e.g. eia-steo)
limit	integer	Page size. Default 100, max 500.

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/load-forecasts?isoRegion=CAISO&metric=annual-energy-twh&targetYear=2026"

Example response

{
  "data": [
    {
      "id": "lf_13e2334bf2634bb9e8c6fdb0",
      "sourceId": "eia-steo",
      "documentId": null,
      "isoRegion": "CAISO",
      "metric": "annual-energy-twh",
      "targetYear": 2026,
      "targetSeason": null,
      "value": 253.59537472,
      "unit": "TWh",
      "scenarioLabel": "reference",
      "notes": null,
      "fetchedAt": "2026-05-14T00:00:00.000Z"
    },
    {
      "id": "lf_nerc_caiso_energy_2026",
      "sourceId": "nerc-ltra",
      "documentId": null,
      "isoRegion": "CAISO",
      "metric": "annual-energy-twh",
      "targetYear": 2026,
      "targetSeason": null,
      "value": 266,
      "unit": "TWh",
      "scenarioLabel": "reference",
      "notes": null,
      "fetchedAt": "2026-05-14T00:00:00.000Z"
    }
  ],
  "meta": { "count": 2, "sources": ["eia-steo", "nerc-ltra"] }
}

GET/api/v1/consensus

Cross-source consensus (min / median / max) for a single (isoRegion, metric, targetYear) tuple. Returns 404 when no rows match.

Query parameters

Param	Type	Description
isoRegion*	string	e.g. CAISO
metric*	string	e.g. annual-energy-twh
targetYear*	integer	e.g. 2026

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/consensus?isoRegion=CAISO&metric=annual-energy-twh&targetYear=2026"

Example response

{
  "data": {
    "isoRegion": "CAISO",
    "metric": "annual-energy-twh",
    "targetYear": 2026,
    "unit": "TWh",
    "min": 253.59537472,
    "max": 266,
    "median": 259.79768736,
    "sourceCount": 2,
    "values": [
      { "sourceId": "eia-steo", "value": 253.59537472 },
      { "sourceId": "nerc-ltra", "value": 266 }
    ]
  }
}

GET/api/v1/datacenter-projects

List tracked datacenter projects, sorted by the larger of operatingMw / announcedMw. Filter by ISO, state, status, or operator.

Query parameters

Param	Type	Description
isoRegion	string	ERCOT \| PJM \| MISO \| ...
state	string	Two-letter US state code (e.g. VA, TX)
status	string	announced \| permitted \| under-construction \| operating \| cancelled
operator	string	e.g. Amazon, Meta, Microsoft

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/datacenter-projects?status=operating"

Example response

{
  "data": [
    {
      "id": "dcp_amazon_ashburn",
      "slug": "amazon-ashburn-va",
      "name": "AWS US-East-1 Ashburn Campus",
      "operator": "Amazon",
      "utilityId": null,
      "isoRegion": "PJM",
      "state": "VA",
      "county": "Loudoun",
      "city": "Ashburn",
      "lat": 39.0438,
      "lng": -77.4874,
      "announcedMw": null,
      "operatingMw": 2500,
      "status": "operating",
      "announcedDate": null,
      "operationalDate": "2020-01-01",
      "sourceUrl": null,
      "sourceNotes": null,
      "sources": [],
      "createdAt": "2026-05-14T00:00:00.000Z",
      "updatedAt": "2026-05-14T00:00:00.000Z"
    }
  ],
  "meta": { "count": 1, "totalAnnouncedMw": 0, "totalOperatingMw": 2500 }
}

GET/api/v1/datacenter-projects/{slug}

Fetch a single datacenter project by slug. 404 when no match.

Query parameters

Param	Type	Description
slug*	string	Path segment, e.g. amazon-ashburn-va

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/datacenter-projects/meta-richland-parish-la"

Example response

{
  "data": {
    "id": "dcp_meta_richland",
    "slug": "meta-richland-parish-la",
    "name": "Meta Richland Parish Hyperion",
    "operator": "Meta",
    "utilityId": null,
    "isoRegion": "MISO",
    "state": "LA",
    "county": "Richland Parish",
    "city": null,
    "lat": null,
    "lng": null,
    "announcedMw": 2000,
    "operatingMw": null,
    "status": "announced",
    "announcedDate": "2024-12-04",
    "operationalDate": null,
    "sourceUrl": null,
    "sourceNotes": null,
    "sources": [],
    "createdAt": "2026-05-14T00:00:00.000Z",
    "updatedAt": "2026-05-14T00:00:00.000Z"
  }
}

GET/api/v1/power-events

Upcoming forecast-release calendar events. Defaults to a 90-day window from today. Filter by ISO.

Query parameters

Param	Type	Description
isoRegion	string	e.g. PJM
from	ISO date	Inclusive lower bound. Defaults to today (UTC).
to	ISO date	Inclusive upper bound. Defaults to 90 days after `from`.

Example request

curl -H "Authorization: Bearer lc_..." \
  "https://loadconsensus.com/api/v1/power-events?isoRegion=PJM"

Example response

{
  "data": [
    {
      "id": "pe_jan_pjm_load_2026",
      "source": "pjm-load-forecast",
      "externalId": null,
      "eventName": "PJM Load Forecast Report 2026",
      "isoRegion": "PJM",
      "category": "forecast-release",
      "date": "2026-01-30T16:00:00.000Z",
      "description": null,
      "url": "https://www.pjm.com/library/reports-notices/load-forecast-report.aspx"
    }
  ],
  "meta": {
    "count": 1,
    "from": "2026-05-15T00:00:00.000Z",
    "to": "2026-08-13T00:00:00.000Z"
  }
}

CSV exports

Per-tier row caps: Pro 50,000, Team 200,000, Enterprise 1,000,000. Files are returned in a single response — no pagination cursors.

curl -H "Authorization: Bearer lc_abc..." \
  "https://loadconsensus.com/api/v1/load-forecasts.csv?isoRegion=ERCOT&metric=annual-energy-twh" \
  -o ercot-forecasts.csv

GET/api/v1/load-forecasts.csv

Latest forecast rows as CSV. Same filters as the JSON sibling. Per-tier row caps: Pro 50K, Team 200K, Enterprise 1M.

Filename

load-forecasts-YYYYMMDD.csv

Columns

id, sourceId, isoRegion, metric, targetYear, targetSeason, value, unit, scenarioLabel, isLatest, fetchedAt

Query parameters

Param	Type	Description
isoRegion	string	ERCOT \| PJM \| MISO \| CAISO \| ISO-NE \| NYISO \| SPP \| NATIONAL
metric	string	peak-demand-gw \| annual-energy-twh \| ...
targetYear	integer	Forecast horizon year.
sourceId	string	Restrict to a single publisher.

GET/api/v1/datacenter-projects.csv

Datacenter pipeline as CSV. Excludes the JSONB `sources` array and long-text `sourceNotes` by default; add `?include=sources,notes` to opt in (rendered as JSON-stringified cells).

Filename

datacenter-projects-YYYYMMDD.csv

Columns

id, slug, name, operator, utilityId, isoRegion, state, city, lat, lng, announcedMw, operatingMw, status, announcedDate, sourceUrl

Query parameters

Param	Type	Description
isoRegion	string	ERCOT \| PJM \| MISO \| ...
state	string	Two-letter US state code.
status	string	announced \| permitted \| under-construction \| operating \| cancelled
operator	string	e.g. Amazon, Meta, Microsoft
include	string	Comma list: `sources`, `notes`.

GET/api/v1/revisions.csv

Forecast revision history. Filter by `since` (ISO date) and `minAbsPct` (only rows where |deltaPct| ≥ N). Same Pro/Team/Enterprise row caps as load-forecasts.csv.

Filename

forecast-revisions-YYYYMMDD.csv

Columns

id, forecastId, sourceId, isoRegion, metric, targetYear, priorValue, deltaAbsolute, deltaPct, recordedAt

Query parameters

Param	Type	Description
since	ISO date	Inclusive lower bound on recordedAt.
minAbsPct	number	Drop rows where \|deltaPct\| < this value.

Webhooks

Event types

Type	Fires when
forecast.revision	A LoadForecast row was updated — payload includes priorValue, newValue, deltaAbsolute, deltaPct, isoRegion, metric, targetYear.
dc.announcement	A new DatacenterProject row was created, or a tracked field changed (operator, status, announcedMw, operatingMw).
jobrun.failure	A cron worker recorded status='failed' in JobRun. Payload includes jobName, fail count, errorSample.

Filters

Each subscription accepts an isoFilters allowlist (empty = all regions) and an optional minDeltaPct floor — forecast.revision events with abs(deltaPct) < minDeltaPct are skipped.

Payload envelope

{
  "id": "whd_<hex>",
  "type": "forecast.revision",
  "createdAt": "2026-05-15T12:00:00.000Z",
  "data": {
    "revisionId": "...",
    "forecastId": "lf_...",
    "sourceId": "eia-steo",
    "isoRegion": "ERCOT",
    "metric": "annual-energy-twh",
    "targetYear": 2026,
    "priorValue": 482.1,
    "newValue": 491.7,
    "unit": "TWh",
    "deltaAbsolute": 9.6,
    "deltaPct": 1.99,
    "recordedAt": "2026-05-15T11:59:42.000Z"
  }
}

Headers

Header	Value
X-LoadConsensus-Signature	sha256=<hex of HMAC-SHA256(secret, raw_body)>
X-LoadConsensus-Event	e.g. forecast.revision
X-LoadConsensus-Delivery	whd_<hex> — unique per attempt

Verifying signatures

Compute the same HMAC over the raw request body and constant-time compare against the header value (strip the sha256= prefix). Reject on mismatch before parsing JSON.

curl + bash

# Receiver side — verify and respond.
# RAW_BODY must be the exact bytes from the request (do not re-serialize).
SECRET="whsec_..."
SIG_HEADER="$HTTP_X_LOADCONSENSUS_SIGNATURE"  # e.g. "sha256=abc123..."
RAW_BODY="$(cat)"

expected="sha256=$(printf '%s' "$RAW_BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" \
  | awk '{print $2}')"

if [ "$expected" = "$SIG_HEADER" ]; then
  echo "OK"; exit 0
else
  echo "signature mismatch"; exit 1
fi

node

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody: string, header: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Delivery + retry policy

At-most-once. No automatic retry.
10-second timeout per POST.
2xx = success. Any non-2xx, network error, or timeout = failure.
Each attempt is recorded in the delivery log at /account/webhooks with response status, latency, and body (first 500 chars).
After 10 consecutive failures the subscription is auto-disabled (isActive=false). Re-enable by creating a new subscription.
Use the per-subscription Test fire button to send a synthetic event end-to-end before relying on the production fan-out.

Errors

All error responses use the shape { error, hint? }. The HTTP status is the source of truth.

401Missing or invalid Authorization header.

{ "error": "unauthorized", "hint": "Include Authorization: Bearer lc_... header" }

402CSV endpoint requested with a Free-tier key (or the local dev bypass). Upgrade to Pro+.

{ "error": "upgrade_required", "hint": "CSV export requires Pro or higher" }

404No row matches the requested slug or (iso, metric, year) tuple.

{ "error": "not_found", "hint": "No forecasts for ERCOT / peak-demand-gw / 2099" }

429Per-key daily quota exhausted. Resets at UTC midnight.

{ "error": "rate_limit_exceeded", "remaining": 0, "reset": 1747353600 }

500Unexpected server error. Safe to retry with backoff.

{ "error": "server_error" }

Changelog

v1.0.02026-05-15
- Initial release.
- Endpoints: /health, /sources, /load-forecasts, /consensus, /datacenter-projects, /datacenter-projects/{slug}, /power-events.
- Bearer-token auth via the ApiKey table. Per-key daily rate limit. X-RateLimit-* headers on every response.