Release Notes

New endpoint for production meter readings is available.

A new endpoint, production_meter_readings, is now available to retrieve cumulative watt hour readings from systems with meters. We recommend using this or energy_lifetime in place of monthly_production. The monthly_prodcution endpoint is now deprecated.

New system statuses are available.

Systems with AC batteries installed may experience two new status: "battery", indicating a communication problem, and "storage_idle", indicating that the battery is neither charging nor discharging.

Added "meta" property to index response.

Each system returned in the index response now includes metadata about the reporting status of that system. (ENL-395) Furthermore the meta property now includes the operational_date of the system.

More changes to energy_lifetime on systems with meters.

Now that energy_lifetime includes a complete time series that may include a mixture of meter- and microinverter-reported data, you can also request to see those time series called out separately. See the documentation for more information. (ENL-314)

Changes to energy_lifetime on systems with meters.

After a meter is installed on a system, the energy_lifetime endpoint no longer included data from before the meter was installed. This has been corrected by including microinverter measurements from before the meter started collecting data, and meter measurements afterward. See the documentation for more information. (Bug 40567)

New metadata in production endpoints.

The endpoints energy_lifetime, monthly_production, rgm_stats, and stats now include metadata about the system's current status, to aid in detecting whether the data returned is up-to-date. The metadata includes the system status, the last time it reported, and the last known time that energy was produced.

Enhancements to systems filtering.

You can now filter by more than one attribute on the systems index endpoint; for example, /api/v2/systems?status=normal&system_name=MySystem. In addition, queries on system_name no longer require an exact match. Instead, all systems whose name contain the requested string are returned. Learn more...

The summary request now includes last_interval_end_at, the last reported time at which energy was produced at the site. See the documentation for more information.

New flexibility for date and time formats.

Now when making a request to an endpoint that returns dates or times in its response, you can request that they be formatted in one of two ways: ISO-8601 or Unix epoch time. See Dates and Times in Requests and Responses for more information.

New error code on monthly_production.

The monthly_production endpoint occasionally returned a 500 status code with an obscure error message. Now, if there is an error retrieving monthly data, the body of the response includes an error code you can inspect. See the monthly_production documentation for details. (Bug 37113)

The summary request includes system size.

The summary endpoint now returns an attribute named "size_w", which is the size of the system measured in Watts. (Enhancement 36797)

Bugfix: monthly_production sometimes fails on new systems.

Fixed the monthly_production endpoint, which could return 0 production in the early days of a system's lifetime. This condition could last from 1 day to up to the first 30 days of the system's lifetime. (Bug 36619)

Bugfix: Some endpoints don't support callbacks.

The endpoints energy_lifetime and inventory now support callbacks. Also fixed callbacks for rgm_stats when the requested site does not have any revenue-grade meters. (Bug 35076)

The Authorization URL supports redirects.

When a user authorizes your application, we can redirect to a URL of your choosing. Add a query parameter named redirect to your Authorization URL, e.g.

https://enlighten.enphaseenergy.com/app_user_auth/new?app_id=123&redirect=http://mydomain.com/enlighten_user_id

This URL must accept GET requests that include a user_id parameter on the query string.

More information provided when requests are throttled.

You can now get detailed information from a throttled request.
When a request is throttled because you have a reached a limit in your application, the response code is 409 and the response body includes information about when you will be able to make a request again. Please see the documentation for details about the response body.

Demo systems now available.

You can now make API requests even if you don't have access to any systems.
A few owners of Enphase systems have given us permission to share their performance data with you so that you can see some representative API responses before writing a line of code. Use your API key and the user_id 4d7a45774e6a41320a to make a request. For example:
https://api.enphaseenergy.com/api/v2/systems?key=<your_api_key>&user_id=4d7a45774e6a41320a

v2.0 is released.

The following changes and features make up v2 of the Enlighten Systems API.

The /api/v2/systems request now supports filtering and pagination.
See the documentation for how to filter and to control pagination parameters.
The /api/v2/systems/ and /api/v2/systems/[id]/envoys responses include status values useful for troubleshooting.
See the documentation for systems and envoys.
The /api/v2/systems/[id]/summary response has changed.
It includes system status, time of last report, and when the system became operational. It no longer includes energy_week or energy_month. Instead, these ranges and other custom ranges can be calculated from energy_lifetime. Learn more...
The /api/v2/systems/[id]/energy_lifetime request now accepts range criteria.
The request accepts parameters start_date and end_date, allowing you to slice the returned time series into custom ranges. Learn more...
The /api/v2/systems/[id]/stats request does not 'pad' the returned array of intervals.
When you request stats for a system, the response includes intervals that have been reported during the requested period. Gaps in reporting are not filled with 0-value intervals.
A new endpoint /api/v2/systems/[id]/inventory has been added.
See the documentation.
The endpoints /api/v2/systems/power_today, power_week, and alerts are removed.
Use the stats request to retrieve power and energy one day at a time for any day up to one year ago. Note that there is no drop-in replacement for the alerts endpoint: Instead, the "status" attribute returned by the systems request conveys information about what type of troubleshooting, if any, is required on a system.
Dates and times are treated distinctly.
To simplify date and time formatting, the following changes apply:
  • Endpoints that receive and return dates expect the format YYYY-mm-dd, and return them as such. All dates are in the timezone of the requested system. Attributes that are dates are named accordingly; e.g., "summary_date", "start_date", "end_date".
  • Endpoints that receive and return times expect the time to be expressed in Unix epoch time, and return it as such.
  • Attributes that are times are named accordingly; e.g., "operational_at", "last_report_at", "start_at", "end_at".
  • In some cases, query parameters such as "start" and "end" did not align with the names of the fields in the response. In v2, all start and end parameters are named according to their datatype; e.g., "start_date" instead of "start" for date parameters and "start_at" instead of "start" for time parameters.