Release Notes

Updates and announcements about our API and data signals.

A 3D icon shows a trio of data visualizations in charts and graphs.


API change

API response status for an invalid token changing from HTTP 403 -> 401

WattTime has changed the HTTP response status code for missing, expired, or invalid authentication tokens in our APIs. 

  Issue    Old Status Code       New Status Code
  Token missing, expired, or invalid      403 Forbidden    401 Authorization Required  

Why might this matter? Some users may have a heuristic in their code that will re-authenticate after a token expires (reminder: tokens are valid for 30 minutes). If your code is designed to re-authenticate when you get an HTTP 403 response, but not if you get an HTTP 401, then you will need to update that heuristic accordingly so that it will properly re-authenticate when you get an HTTP 401.

Contact if you have questions or concerns about this upcoming change.


bug fix

Data correction: `co2_aoer` in US regions between 21 Oct 2023 - 29 Jan 2024

WattTime published some erroneous values for CO2 AOER due to a change in the data reported by the US EIA. These erroneous values were backfilled with new data on Jan 29. If you store AOER data for future use, we recommend you re-pull AOER data for all 53 US regions (region list as csv download: My_access_list_aoer_US), for October through January. If you are using v3/historical, you can use the new `updated_since` parameter to pull just the data points that are new, i.e. 'updated_since': '2024-01-29T00:00:00+00:00' .  Another option is to pull the entire months of October through January to replace all the data you previously pulled for these months. Please contact if you would like support with this.


new regions

12 new countries

Coverage of the `co2_moer` signal has expanded to 12 new countries (21 new regions). These new regions are only available in API v3. A new type of `co2_moer` model is used for many of these new countries, learn more about that model type here. New countries: Mexico, Japan, South Korea, Brazil, India, Chile, Peru, Turkey, Malaysia, Nicaragua, Philippines, Singapore.

new feature

New signal: health damage

WattTime is excited to offer a new signal measuring the marginal damage to human health from electricity use. Read more about the health damage signal here. It is initially available in US grid regions only. Please contact us if you’d like to obtain access to this new signal.

API change

New data model versioning

Data model versioning in the new API uses dates instead of decimals. Each model will be labeled with a date string that roughly corresponds to its release date. Model dates can be unique to each combination of grid region and signal type. A full list of available model date versions can be obtained by using the /v3/my-access endpoint.

API change

APIv3 release

WattTime released API version 3 that provides expanded functionality including more intuitive and descriptive data delivery, signal information, and error handling. The old API (version 2) will continue to be supported until June 2024. A detailed transition guide explaining the differences between the old v2 API and the new v3 API can be found here.


bug fix

Forecast bug fix

Fixed bug that affected forecast requests that used local time for ‘starttime’ and ‘endtime’ parameters.


data model update

CO2 MOER model upgrade

This `co2_moer` data model release improves our renewable curtailment modeling, and only applies where we model renewable curtailment. For ISOs where curtailment ground truth data is available, we train a supervised ML model to predict in real-time whether curtailment is occurring. We then apply a region-specific threshold to the relevant LMP prices as an additional filter in creating a curtailment probability value (LMP threshold used exclusively where ground truth is not available). This model version is not available in APIv2, it was only released in APIv3-beta (as meta=3.3), and will later be available in APIv3 (as `2023-03-01`).


data model update

CO2 MOER 3.2

We’ve improved our detection of marginality for certain fuel types, and we’ve also retrained our models on more recent data to reflect structural grid changes like plant retirements.

  • We no longer consider reservoir hydroelectric to be a marginal fuel source in any grid region. This change has the largest effect on grid regions such as BPA, SCL, TVA, DUK, SCEG, and ISONE where hydro was previously considered marginal in the 3.0 model version. After extensive research, we are confident that water resources in these regions are not regularly being “spilled” or wasted; consequentially that is to say that if you choose not to dispatch electricity during a given time, water resources will be saved for a later time rather than wasted. Pumped hydro storage is still capable of operating on the margin and is included in our models as a form of storage. 
  • We changed our handling of nuclear power plants: across the US, we have found little evidence that nuclear power is capable of sustained marginal operation. While it can respond to miniscule changes in instantaneous demand as a form of ancillary services, it does not operate with enough headroom to respond to 100+ MW changes in demand. Previously, nuclear was permitted to be marginal in some regions such as ISONE and CAISO. However in Europe, we have found evidence that reactors ramp to meet load (or some reactors turn on only as "peakers") in nuclear heavy countries such as France, Belgium, Czechia, and Slovakia. In these countries, we now allow nuclear power to be marginal if and when statistical evidence shows it is likely to be responsive, resulting in periods of decreased MOERs for these regions. This can also decrease MOERs in neighboring or interconnected regions, because of the impact of imports and exports (Estonia, Sweden, and Norway are particularly affected by this update).
  • More detailed carbon intensity models for gas and coal plants provide additional granularity towards which plants of these fuel sources are marginal in the US; for instance, we better capture effects such as relatively dirtier gas during peak periods. Additionally, the carbon intensity of petroleum fuel plants is now modeled. 
  • Our models have been improved to better capture differences in power consumption between weekdays and weekends.


data model update

CO2 AOER model upgrade

Standardized time-series frequency to 1-hour in all regions.  Improved robustness to extended source data outages. Updated reference emissions factors to IEA 2019. Changed data source for CAISO from CAISO to IEA to ensure the calculation methodology is consistent in all regions.