History

These endpoints for retreiving the data about the energy generated or stored by the products at a site, such as the power generated by Solar panels and the energy stored in a Powerwall.

The statistics can either be instantaneous power generation/storage in watts at 15 minute intervals for a day, or cumulative energy in kWh generated/stored in a day, week, month, or year. Depending on your equipment, some statistics may be unsupported and always return 0.

GET /api/1/energy_sites/{site_id}/history

Retrieves either the power generation/storage (watts) for the previous day, or the cumulative energy generation/storage (kWh) for a specified recent period.

Request parameters

Field	Type	Example	Description
kind	String, required	power or energy	power selects power statistics, in watts, at 15-minute intervals. energy selects energy statistics, in kWh, for a specified period.
period	String	day, week, month, or year	The time span for energy statistics to cover.

When kind=power, the period parameter is not required, and is ignored if present. When kind=energy, the period parameter is required and the value determines the time span of the retrieved data items:

Value	Statistics returned
day	Total kWh for yesterday, and for today up to the current time.
week	Total kWh for each of the past 7 days, not including today.
month	Total kWh for each of the past 4 weeks, not including the current week. Weeks are Sunday to Saturday; timestamps are for Saturdays.
year	Total kWh for each of the past 12 months, not including the current month.

Response when kind=power

{
  "response": {
    "serial_number": "313dbc37-555c-45b1-83aa-62a4ef9ff7ac",
    "time_series": [
      {
        "timestamp": "2022-05-13T00:00:00-07:00",
        "solar_power": 0,
        "battery_power": 0,
        "grid_power": 0,
        "grid_services_power": 0,
        "generator_power": 0
      }
    ]
  }
}

The solar_power value is the power being generated, in watts, at the given timestamp. To save space, only the first entry is shown in the time_series array. In a real response there are many entries in the array: one entry for each 15 minutes, starting at the beginning (midnight) of the previous day and ending at the current time and day. The entries cover 24 - 48 hours, depending on when the request is made. Depending on your equipment, some nighttime samples may be omitted if they are all zeroes.

Response when kind=energy

{
  "response": {
    "serial_number": "313dbc37-555c-45b1-83aa-62a4ef9ff7ac",
    "period": "week",
    "time_series": [
      {
        "timestamp": "2022-05-09T01:00:00-07:00",
        "solar_energy_exported": 18630,
        "generator_energy_exported": 0,
        "grid_energy_imported": 0,
        "grid_services_energy_imported": 0,
        "grid_services_energy_exported": 0,
        "grid_energy_exported_from_solar": 0,
        "grid_energy_exported_from_generator": 0,
        "grid_energy_exported_from_battery": 0,
        "battery_energy_exported": 0,
        "battery_energy_imported_from_grid": 0,
        "battery_energy_imported_from_solar": 0,
        "battery_energy_imported_from_generator": 0,
        "consumer_energy_imported_from_grid": 0,
        "consumer_energy_imported_from_solar": 0,
        "consumer_energy_imported_from_battery": 0,
        "consumer_energy_imported_from_generator": 0
      }
    ]
  }
}

The solar_energy_exported value is the energy generated by the solar panels, in kWh. To save space, only the first entry is shown in the time_series array. In a real response there are multiple entries in the array, depending on the value of the period parameter. For example, if the period value is week, there are 7 entries, each one representing the energy generated for one day.

GET /api/1/energy_sites/{site_id}/calendar_history

Retrieves either the power generation/storage (watts) at 15-minute intervals for a given day, or the energy generation/storage (kWh) for a specified period.

Request parameters

Field	Type	Example	Description
kind	String, required	power or energy	power selects power statistics, in watts, at 15-minute intervals. energy selects energy statistics, in kWh, for a specified period.
end_date	Date/time, required	2022-04-29T14:15:00-07:00	Specifies the last day for which statistics are retrieved.
period	String	day, week, month, year, or lifetime	The time span for energy statistics to cover.
interval	String	15m	For 15 minute energy intervals when period is day (raises an error when tested on a number of other period/interval values)

The format for the end_date parameter value is "yyyy-mm-ddThh:mm:ss-hh:mm". Specify your local time zone offset for best clarity. Universal time is accepted in the format "yyyy-mm-ddThh:mm:ssZ", but the time is converted to your local time zone, which could also change the date.

When kind=power, the period parameter is not required, and is ignored if present. When kind=energy, the period parameter is required and the value determines the time span of the retrieved data items:

Value	Statistics returned
day	Total kWh for the day specified by end_date.
week	Total kWh for each day from the previous Monday to, and including, end_date.
month	Total kWh for each day from the first of the month to, and including,end_date.
year	Total kWh for each calendar month from the previous January to, and including, end_date.
lifetime	Total kWh for each calendar year from installation to, and including, end_date.

interval is optional, and can only be used with day. So far the only confirmed valid value is 15m. This returns the daily data in 15 minute increments, and is referred to as the day/15m period below.

The output of the energy requests is a little erratic, with the following behaviours observed in data taken from a single powerwall with a 3 month lifetime:

• Calls for the full day based periods (day, week, and month, but not the day/15m period) typically yield identical results for a given date-time range, with the exception that month data can omit a day (and possibly more than one). This occurred only once in the data set, corresponding to misconfigured CT, where the house was reporting energy production rather than draw. The API dropped the odd value from the monthly data, and provided an adjusted value for the weekly and daily data. Adding the adjusted missing day into the monthly cumulative values resulted in identical data for day, week, and month calls.

• Output for year and lifetime periods is similar to, but not equal to, the output from the day based periods. Differences between the cumulative energy flows over a 3 month period can be as high as 20-30kWh. The worst case is lifetime home load, which is 34 kWh lower than cumulative daily home load over the lifetime (828 vs 863 kWh).

• However, output for full and partial days is mostly consistent across all period types except the day/15m. That is, the same full or partial day output will be reported for all periods for most days in a given date-time range. Based on the cumulative tests discussed above, this conclusion can be extended across fairly long multi-day periods. Inconsistent output corresponds to the differences already highlighted above. Unfortunately, I have not been able to identify the cause/pattern for the inconsistent daily data, nor the calculations that yield the inconsistent values.

• Based on a small random sample of days (so these observations and conclusions should be treated with caution):

  • Up to a variable time in the day, the cumulative day/15m output for the component energy types matches the output for the partial day up to the same time.

  • After this time the day/15m and day component energy types deviate. However, the total imports/exports to/from the system still appear to match. So it appears Tesla may apply slightly different allocations calculations for these two period types.

• If end_date has a time value of midnight (00:00:00:000), then:

  • For all period types except day/15m, the output for day of end_date will be zero for all energy component types.

  • For the day/15m period type, output will be reported for all energy component types, but this data appears to be garbage.

• There is no clear alignment between the Tesla cloud API data and the data available from the local Powerwall API.

For anyone is interested in investigating further (and hopefully resolving some of the differences identified above), this gist provides a first draft python class for extracting energy data for multiple periods.

Response when kind=power

{
  "response": {
    "serial_number": "313dbc37-555c-45b1-83aa-62a4ef9ff7ac",
    "time_zone_offset": -420,
    "time_series": [
      {
        "timestamp": "2022-04-29T00:00:00-07:00",
        "solar_power": 0,
        "battery_power": 0,
        "grid_power": 0,
        "grid_services_power": 0,
        "generator_power": 0
      }
    ]
  }
}

The solar_power value is the power being generated, in watts, at the given timestamp. To save space, only the first entry is shown in the time_series array. In a real response, there is one entry for each 15 minutes, starting at the beginning (midnight) of the specified date and ending at the specified time. To retrieve a full day's records, specify an ending time after sunset, or 23:45:00. Don't use 00:00:00 for the time, or you'll retrieve an empty list.

Response when kind=energy

{
  "response": {
    "serial_number": "313dbc37-555c-45b1-83aa-62a4ef9ff7ac",
    "period": "year",
    "time_zone_offset": -420,
    "time_series": [
      {
        "timestamp": "2021-01-01T01:00:00-07:00",
        "solar_energy_exported": 152680,
        "generator_energy_exported": 0,
        "grid_energy_imported": 0,
        "grid_services_energy_imported": 0,
        "grid_services_energy_exported": 0,
        "grid_energy_exported_from_solar": 0,
        "grid_energy_exported_from_generator": 0,
        "grid_energy_exported_from_battery": 0,
        "battery_energy_exported": 0,
        "battery_energy_imported_from_grid": 0,
        "battery_energy_imported_from_solar": 0,
        "battery_energy_imported_from_generator": 0,
        "consumer_energy_imported_from_grid": 0,
        "consumer_energy_imported_from_solar": 0,
        "consumer_energy_imported_from_battery": 0,
        "consumer_energy_imported_from_generator": 0
      }
    ]
  }
}

solar_energy_exported is the energy generated by the solar panels, in kWh. To save space only the first entry in the time_series array is shown. In a real response, the number of entries in the array depends on the period and end_date values. Timestamps in the response represent the start of a period; e.g., monthly statistics for February show a date of February 1st in the timestamp, and daily statistics for February 15th show a timestamp of 1:00 AM on February 15th.