Regions

Get Historical Actuals

View as Markdown

Retrieve historical observed values for a specific metric, ISO and time period.

Data may only be available on a lagged basis, and is currently limited to history from January 1, 2023 onwards.

Access: Requires core subscription level.

Authentication

X-API-Keystring

API key for authentication. Can also be provided in the api_key query parameter.

Path parameters

isoenumRequired
ISO identifier.
metricenumRequired
Forecast metric type.
Allowed values:

Query parameters

startdatetimeOptional
enddatetimeOptional
idstringOptional

Unique identifier of the specific target (region, plant, county, or hub). If omitted, returns all available targets for the specified ISO.

Response

Successful Response
modelstring or null

Identifier of the weather model used for this forecast (e.g., ‘optimized’, ‘iso’). Null for historical actuals or composite responses.

created_atdatetime or null

Timestamp (UTC) when this forecast was created/published. Represents the model run time. Null for continuous/stitched forecasts or historical actuals.

unitsstring

Measurement units for all data values in the response. Common values: ‘MW’ (megawatts), ‘°C’ (degrees Celsius), ‘USD/MWh’, ’$/MMBtu’.

timezonestringformat: "zoneinfo"

IANA timezone identifier used for the time_local field. Typically matches the region’s local timezone.

time_utclist of datetimes

Array of timestamps in Coordinated Universal Time (UTC). Each entry corresponds to one row in the values matrix. Always timezone-aware.

time_locallist of datetimes

Array of timestamps in local time (timezone specified in timezone field). Each entry corresponds to one row in the values matrix. Parallel to time_utc.

columnslist of lists of strings

Metadata describing each column in the values matrix. Each entry is a list of one or more level labels — single-level columns are returned as length-1 sublists (e.g. [‘pjm_total’]); naturally multi-level data uses one entry per level (e.g. [‘pjm_total’, ‘demand’]). Clients can rebuild a pandas MultiIndex via pd.MultiIndex.from_tuples(columns).

valueslist of lists of nullable doubles

2D matrix of numeric forecast or actual values in column-major order. Each inner list represents a series (corresponding to columns), and each element within that list corresponds to a timestamp (corresponding to time_utc/time_local). Missing or unavailable data is represented as null.

Errors

422
Unprocessable Entity Error