# 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` ```json { "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` ```json { "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](https://gist.github.com/BuongiornoTexas/3ea2d1df1a569e1a0a4bc79878a8a753) provides a first draft python class for extracting energy data for multiple periods. ### Response when `kind=power` ```json { "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` ```json { "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.