openapi: 3.2.0 info: title: Site Level Consumption Monitoring API version: v4 servers: - url: https://api-qa2.enphaseenergy.com tags: - name: Site Level Consumption Monitoring paths: /api/v4/systems/{system_id}/consumption_meter_readings: get: summary: consumption_meter_readings description: Returns the last known reading of each consumption meter on the system as of the requested time, regardless of whether the meter is currently in service or retired. Read_at is the time at which the reading was taken, and is always less than or equal to the requested end_at. Commonly, the reading will be within 30 minutes of the requested end_at. However, larger deltas can occur and do not necessarily mean there is a problem with the meter or the system. Systems that are configured to report infrequently can show large deltas on all meters, especially when end_at is close to the current time. Meters that have been retired from a system will show an end_at that doesn’t change, and that eventually is far away from the current time. tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: end_at in: query description: End of reporting period in Unix epoch time. If no end is specified, defaults to the time of the request. If the end is later than the last reported interval the response data ends with the last reported interval schema: type: integer responses: '200': description: consumption_meter_readings content: application/json: schema: type: object properties: system_id: type: integer description: System id meter_readings: type: array items: properties: serial_num: type: string description: the serial number of the meter value: type: integer description: the meter reading, in Wh read_at: type: integer description: the time when the reading was taken, always prior or equal to the requested 'end_at' description: Consumption Meter Readings meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 66 meter_readings: - serial_num: 123123123123EIM2 value: 6180635 read_at: 1473901200 meta: status: normal last_report_at: 1473902079 last_energy_at: 1473901200 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Failed to parse date 1613543106 code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code period: type: string description: Quota exceeded for minute/month period_start: type: integer description: Starting period timestamp period_end: type: integer description: Ending period timestamp limit: type: integer description: Limit count for the period example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 period: minute period_start: 1623825660 period_end: 1623825720 limit: 5 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/storage_meter_readings: get: summary: storage_meter_readings description: Returns the last known reading of each storage meter on the system as of the requested time, regardless of whether the meter is currently in service or retired. Read_at is the time at which the reading was taken, and is always less than or equal to the requested end_at. Commonly, the reading will be within 30 minutes of the requested end_at. However, larger deltas can occur and do not necessarily mean there is a problem with the meter or the system. Systems that are configured to report infrequently can show large deltas on all meters, especially when end_at is close to the current time. Meters that have been retired from a system will show an end_at that doesn’t change, and that eventually is far away from the current time. tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: end_at in: query description: End of reporting period in Unix epoch time. If no end is specified, defaults to the time of the request. If the end is later than the last reported interval the response data ends with the last reported interval schema: type: integer responses: '200': description: storage_meter_readings content: application/json: schema: type: object properties: system_id: type: integer description: System id meter_readings: type: array items: properties: serial_num: type: string description: the serial number of the meter value_charged: type: integer description: the meter reading for energy charged, in Wh value_discharged: type: integer description: the meter reading for energy discharged, in Wh read_at: type: integer description: the time when the reading was taken, always prior or equal to the requested 'end_at' description: Storage Meter Readings meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 66 meter_readings: - serial_num: 482520034566EIM4 value_charged: 137436 value_discharged: 2689 read_at: 1762753711 meta: status: normal last_report_at: 1473902079 last_energy_at: 1473901200 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Failed to parse date 1613543106 code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code period: type: string description: Quota exceeded for minute/month period_start: type: integer description: Starting period timestamp period_end: type: integer description: Ending period timestamp limit: type: integer description: Limit count for the period example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 period: minute period_start: 1623825660 period_end: 1623825720 limit: 5 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/consumption_lifetime: get: summary: consumption_lifetime description: "Returns a daily time series of energy consumption as measured by the consumption meter installed on the specified system. All measurements are in Watt hours.\n The time series includes one entry for each day from the start_date to the end_date. There are no gaps in the time series. If the response includes trailing zeroes, such as [909, 4970, 0, 0, 0], then no data has been reported for the last three days." tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: start_date in: query description: Requested start date of the time series data. Defaults to the system’s operational date. If the start_date is earlier than the system’s operational_date, then the response data begins with the system operational_date as start_date. Pass as String date format YYYY-MM-DD. schema: type: string - name: end_date in: query description: End date of the time series data. Defaults to yesterday if start_date is earlier than the system’s current date; it defaults to today if start_date is the current date. Pass as String date format YYYY-MM-DD. schema: type: string responses: '200': description: consumption_lifetime content: application/json: schema: type: object properties: system_id: type: integer description: The unique numeric ID of the system start_date: type: string description: When no start_date parameter is specified on the request, defaults to the operational_date of the system. May be null if system has never produced. When a start_date parameter is included in the request, the same is included in the response consumption: type: array description: An array of consumption measurements in Wh, one for each day since consumption metering began, or one for each day of the requested period items: type: integer meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 66 start_date: '2016-08-01' consumption: - 15422 - 15421 - 17118 - 18505 - 18511 - 18487 meta: status: normal last_report_at: 1470087000 last_energy_at: 1470086106 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Requested date is in the future code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/battery_lifetime: get: summary: battery_lifetime description: Returns a daily time series of energy charged into the batteries and energy discharged from the batteries for a system over its lifetime. All measurements are in Watt hours. The time series includes one entry for each day from the start_date to the end_date with no gaps in the time series. If the response includes trailing zeroes, such as [909, 4970, 0, 0, 0], then no energy has been charged/discharged for the last days in the series. tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: start_date in: query description: Requested start date of the time series data. Defaults to the system’s operational date. If the start_date is earlier than the system’s operational_date, then the response data begins with the system operational_date as start_date. Pass as String date format YYYY-MM-DD. schema: type: string - name: end_date in: query description: End date of the time series data. Defaults to yesterday if start_date is earlier than the system’s current date; it defaults to today if start_date is the current date. Pass as String date format YYYY-MM-DD. schema: type: string responses: '200': description: battery_lifetime content: application/json: schema: type: object properties: system_id: type: integer description: The unique numeric ID of the system start_date: type: string description: When no start_date parameter is specified on the request, defaults to the operational_date of the system. May be null if system has never produced. When a start_date parameter is included in the request, the same is included in the response charge: type: array description: An array of charge measurements, one for each day since the system started producing, or one for each day of the requested period. If the system has never produced energy, the array may be empty items: type: integer discharge: type: array description: An array of dicharge measurements, one for each day since the system started producing, or one for each day of the requested period. If the system has never produced energy, the array may be empty items: type: integer meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 66 start_date: '2016-08-01' discharge: - 15422 - 15421 - 17118 - 18505 - 18511 - 18487 charge: - 15422 - 15421 - 17118 - 18505 - 18511 - 18487 meta: status: normal last_report_at: 1470087000 last_energy_at: 1470086106 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Requested date is in the future code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/energy_import_lifetime: get: summary: import_lifetime description: Returns a daily time series of energy imported to the grid by the system over its lifetime. All measurements are in Watt hours. The time series includes one entry for each day from the start_date to the end_date with no gaps in the time series. If the response contains trailing zeroes, such as [909, 4970, 0, 0, 0], then no energy has been imported for the last days in the series. tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: start_date in: query description: Requested start date of the time series data. Defaults to the system’s operational date. If the start_date is earlier than the system’s operational_date, then the response data begins with the system operational_date as start_date. Pass as String date format YYYY-MM-DD. schema: type: string - name: end_date in: query description: End date of the time series data. Defaults to yesterday if start_date is earlier than the system’s current date; it defaults to today if start_date is the current date. Pass as String date format YYYY-MM-DD. schema: type: string responses: '200': description: import_lifetime content: application/json: schema: type: object properties: system_id: type: integer description: The unique numeric ID of the system start_date: type: string description: When no start_date parameter is specified on the request, defaults to the operational_date of the system. May be null if system has never produced. When a start_date parameter is included in the request, the same is included in the response import: type: array description: An array of import measurements, one for each day since the system started producing, or one for each day of the requested period. If the system has never produced energy, the array may be empty items: type: integer meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 66 start_date: '2016-08-01' import: - 15422 - 15421 - 17118 - 18505 - 18511 - 18487 meta: status: normal last_report_at: 1470087000 last_energy_at: 1470086106 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Requested date is in the future code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/energy_export_lifetime: get: summary: export_lifetime description: Returns a daily time series of energy exported to the grid by the system over its lifetime. All measurements are in Watt-hours. The time series includes one entry for each day from the start_date to the end_date with no gaps in the time series. If the response contains trailing zeroes, such as [909, 4970, 0, 0, 0], then no energy has been exported for the last days in the series. tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: start_date in: query description: Requested start date of the time series data. Defaults to the system’s operational date. If the start_date is earlier than the system’s operational_date, then the response data begins with the system operational_date as start_date. Pass as String date format YYYY-MM-DD. schema: type: string - name: end_date in: query description: End date of the time series data. Defaults to yesterday if start_date is earlier than the system’s current date; it defaults to today if start_date is the current date. Pass as String date format YYYY-MM-DD. schema: type: string responses: '200': description: export_lifetime content: application/json: schema: type: object properties: system_id: type: integer description: The unique numeric ID of the system start_date: type: string description: When no start_date parameter is specified on the request, defaults to the operational_date of the system. May be null if system has never produced. When a start_date parameter is included in the request, the same is included in the response export: type: array description: An array of export measurements, one for each day since the system started producing, or one for each day of the requested period. If the system has never produced energy, the array may be empty items: type: integer meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 66 start_date: '2016-08-01' export: - 15422 - 15421 - 17118 - 18505 - 18511 - 18487 meta: status: normal last_report_at: 1470087000 last_energy_at: 1470086106 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Requested date is in the future code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/telemetry/battery: get: summary: Retrieves telemetry for all batteries for a system description: "Retrieves telemetry for all the batteries of a system. \nIf no start_at is specified, defaults to midnight today, in the timezone of the system. If the start_at specified is earlier than the system’s first reported date, then midnight of the system’s first reported date is considered as start_at.\nThe end_at is calculated as the minimum of the time of the request and (start time + granularity). \nThe meaning of granularity is as follow:\n\nIf granularity is 15mins, maximum 1 interval will appear in response. If granularity is day, maximum 96 intervals, and if granularity is week, maximum 672 intervals, will appear in response where each interval is of 15 mins duration.\n \n The requested start date must be within 2 years from current date. \n By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. \nBy default end_at will appear in response. If end_date parameter is passed in the url then end_date field will appear in response. Empty list will be returned if the last interval < requested start time < current time." tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: System id required: true schema: type: integer - name: start_at in: query description: Start time for fetching the telemetry data in Epoch time format. Alternatively one can use start_date in place of start_at for passing the start date as String date format YYYY-MM-DD. By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. schema: type: integer - name: granularity in: query description: The granularity of the telemetry data. Possible values are 'week', 'day', '15mins', '5mins'. Default is 'day' schema: type: string enum: - 5mins - 15mins - day - week responses: '200': description: Telemetry for batteries content: application/json: schema: type: object properties: system_id: type: integer description: The unique numeric ID of the system granularity: type: string description: The granularity of the telemetry data. Possible values are 'week', 'day', '15mins', '5mins'. Default is 'day' total_devices: type: integer description: Number of Batteries in the site start_at: type: integer description: Start Time of the data series. Either Start_date or start_at will be present. By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. end_at: type: integer description: End Time of the data series. Either end_date or end_at will be present. By default end_at will appear in response. If end_date parameter is passed in the url, then end_date field will appear in response. items: type: string description: The list key 'intervals' intervals: type: array items: properties: end_at: type: integer description: End time of the telemetry interval. charge: type: object properties: enwh: type: integer description: Energy into the battery during the interval devices_reporting: type: integer description: Number of devices reporting discharge: type: object properties: enwh: type: integer description: Energy discharged from the battery during the interval devices_reporting: type: integer description: Number of devices reporting soc: type: object properties: percent: type: integer description: Battery soc percentage devices_reporting: type: integer description: Number of devices reporting last_reported_aggregate_soc: type: string description: Last reported aggregate soc percentage example: system_id: 698905955 granularity: day total_devices: 9 start_at: 1496526300 end_at: 1496529300 items: intervals intervals: - end_at: 1384122700 charge: enwh: 40 devices_reporting: 1 discharge: enwh: 0 devices_reporting: 4 soc: percent: 25 devices_reporting: 4 last_reported_aggregate_soc: 97% '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Invalid request because of 'Requested date range is invalid for this system. {:start_at=>1566930600, :end_at=>1565333100, :first_interval=>1565072100, :last_interval=>1565333700}' code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code period: type: string description: Quota exceeded for minute/month period_start: type: integer description: Starting period timestamp period_end: type: integer description: Ending period timestamp limit: type: integer description: Limit count for the period example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 period: minute period_start: 1623825660 period_end: 1623825720 limit: 5 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/telemetry/consumption_meter: get: summary: Retrieves telemetry for all consumption meters for a system description: "Retrieves telemetry for all the consumption meters of a system. \nIf the start_at specified is earlier than the system’s first reported date, then midnight of the system’s first reported date is considered as start_at.\nThe end_at is calculated as the minimum of the time of the request and (start time + granularity). \nThe meaning of granularity is as follow:\n If granularity is 15mins, maximum 1 interval will appear in response. If granularity is day, maximum 96 intervals, and if granularity is week, maximum 672 intervals, will appear in response where each interval is of 15 mins duration.\n \n The requested start date must be within 2 years from current date. \n By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. \nBy default end_at will appear in response. If end_date parameter is passed in the url then end_date field will appear in response. Empty list will be returned if the last interval < requested start time < current time." tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: start_at in: query description: Requested start time for telemetry data in Epoch time format. Alternatively one can use start_date in place of start_at for passing the start date as String in YYYY-MM-DD format. If no start_at is specified, defaults to midnight today, in the timezone of the system. If the start_at specified is earlier than the system’s first reported date, then the system first reported date is considered as start_at. By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. schema: type: integer - name: granularity in: query description: The granularity of the telemetry data. Possible values are 'week', 'day', '15mins', '5mins'. Default is 'day' schema: type: string enum: - 5mins - 15mins - day - week responses: '200': description: Telemetry for all consumption meters content: application/json: schema: type: object properties: system_id: type: integer description: The unique numeric ID of the system granularity: type: string description: The granularity of the telemetry data. Possible values are 'week', 'day', '15mins', '5mins'. Default is 'day' total_devices: type: integer description: Number of non-retired consumption meters in the site start_at: type: integer description: Start Time of the data series. Either Start_date or start_at will be present. By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. end_at: type: integer description: End Time of the data series. Either end_date or end_at will be present. By default end_at will appear in response. If end_date parameter is passed in the url, then end_date field will appear in response. items: type: string description: The list key 'intervals' intervals: type: array items: properties: end_at: type: integer description: End time of the telemetry interval devices_reporting: type: integer description: Number of devices reporting enwh: type: integer description: Units produced per interval meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 698905955 granularity: day total_devices: 9 start_at: 1496526300 end_at: 1496529300 items: intervals intervals: - end_at: 1384122700 devices_reporting: 1 enwh: 40 - end_at: 1384123600 devices_reporting: 1 enwh: 40 meta: status: normal last_report_at: 1445619615 last_energy_at: 1445619033 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Invalid request because of 'Requested date range is invalid for this system. {:start_at=>1566930600, :end_at=>1565333100, :first_interval=>1565072100, :last_interval=>1565333700}' code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code period: type: string description: Quota exceeded for minute/month period_start: type: integer description: Starting period timestamp period_end: type: integer description: Ending period timestamp limit: type: integer description: Limit count for the period example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 period: minute period_start: 1623825660 period_end: 1623825720 limit: 5 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/energy_import_telemetry: get: summary: Retrieves energy imported from grid in regular intervals description: 'Retrieves energy imported from grid in regular intervals. If no start_at is specified, defaults to midnight today, in the timezone of the system. If the start_at specified is earlier than the system’s first reported date, then midnight of the system’s first reported date is considered as start_at. The end_at is calculated as the minimum of the time of the request and (start time + granularity). The meaning of granularity is as follow: If granularity is 15mins, maximum 1 intervals will appear in response. If granularity is day, maximum 96 intervals will appear in response where each interval is of 15 mins duration. The requested start date must be within 2 years from current date. Empty list will be returned if the last interval < requested start time < current time.' tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: start_at in: query description: Start time for fetching the telemetry data in Epoch time format. Alternatively one can use start_date in place of start_at for passing the start date as String in YYYY-MM-DD format. By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. schema: type: integer - name: granularity in: query description: The granularity of the telemetry data. Possible values are 'week', 'day', '15mins', '5mins'. Default is 'day' schema: type: string enum: - 5mins - 15mins - day - week responses: '200': description: Energy import telemetry in intervals content: application/json: schema: type: object properties: system_id: type: integer description: The unique numeric ID of the system granularity: type: string description: The granularity of the telemetry data. Possible values are 'week', 'day', '15mins', '5mins'. Default is 'day' total_devices: type: integer description: Total devices will always return 0 for this endpoint start_at: type: integer description: Start Time of the data series. Either start_date or start_at will be present. By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. end_at: type: integer description: End Time of the data series. Either end_date or end_at will be present. By default end_at will appear in response. If end_date parameter is passed in the url then end_date field will appear in response. items: type: string description: The list key 'intervals' intervals: type: array description: An array of telemetry objects. Each object contains items: type: array items: properties: end_at: type: integer description: End time of the telemetry interval wh_exported: type: integer description: Energy imported (in Watt-Hours) during that period meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 698905955 granularity: day total_devices: 0 start_at: 1496526300 end_at: 1496528300 items: intervals intervals: - - end_at: 1384122700 wh_imported: 40 - end_at: 1384123600 wh_imported: 40 meta: status: normal last_report_at: 1445619615 last_energy_at: 1445619033 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Invalid request because of 'Requested date range is invalid for this system. {:start_at=>1566930600, :end_at=>1565333100, :first_interval=>1565072100, :last_interval=>1565333700}' code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/energy_export_telemetry: get: summary: Retrieves energy exported to grid in regular intervals description: 'Retrieves energy exported to grid in regular intervals. If no start_at is specified, defaults to midnight today, in the timezone of the system. If the start_at specified is earlier than the system’s first reported date, then midnight of the system’s first reported date is considered as start_at. The end_at is calculated as the minimum of the time of the request and (start time + granularity). The meaning of granularity is as follow: If granularity is 15mins, maximum 1 intervals will appear in response. If granularity is day, maximum 96 intervals will appear in response where each interval is of 15 mins duration. The requested start date must be within 2 years from current date. Empty list will be returned if the last interval < requested start time < current time.' tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer - name: start_at in: query description: Start time for fetching the telemetry data in Epoch time format. Alternatively one can use start_date in place of start_at for passing the start date as String in YYYY-MM-DD format. By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. schema: type: integer - name: granularity in: query description: The granularity of the telemetry data. Possible values are 'week', 'day', '15mins', '5mins'. Default is 'day' schema: type: string enum: - 5mins - 15mins - day - week responses: '200': description: Energy export telemetry in intervals content: application/json: schema: type: object properties: system_id: type: integer description: The unique numeric ID of the system granularity: type: string description: The granularity of the telemetry data. Possible values are 'week', 'day', '15mins', '5mins'. Default is 'day' total_devices: type: integer description: Total devices will always return 0 for this endpoint start_at: type: integer description: Start Time of the data series. Either start_date or start_at will be present. By default start_at will appear in response. If start_date parameter is passed in the url, then start_date field will appear in response. end_at: type: integer description: End Time of the data series. Either end_date or end_at will be present. By default end_at will appear in response. If end_date parameter is passed in the url then end_date field will appear in response. items: type: string description: The list key 'intervals' intervals: type: array description: An array of telemetry objects. Each object contains items: type: array items: properties: end_at: type: integer description: End time of the telemetry interval wh_exported: type: integer description: Energy exported (in Watt-Hours) during that period meta: type: object properties: status: type: string description: System's status. Corresponding Enlighten values can be found in table added at the end of page. last_report_at: type: integer description: Timestamp (in epoch format) at which the system's Envoy last submitted a report last_energy_at: type: integer description: Timestamp (in epoch format) at which the systems's produced energy was last reported. Even if the last produced energy is 0, its timestamp will be returned. operational_at: type: integer description: Timestamp (in epoch format) at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first reported interval end time. description: Information about the system such as its status, when it became operational and last reported to Envoy. example: system_id: 698905955 granularity: day total_devices: 0 start_at: 1496526300 end_at: 1496528300 items: intervals intervals: - - end_at: 1384122700 wh_exported: 40 - end_at: 1384123600 wh_exported: 40 meta: status: normal last_report_at: 1445619615 last_energy_at: 1445619033 operational_at: 1357023600 '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Unprocessable Entity details: Invalid request because of 'Requested date range is invalid for this system. {:start_at=>1566930600, :end_at=>1565333100, :first_interval=>1565072100, :last_interval=>1565333700}' code: 422 '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented /api/v4/systems/{system_id}/latest_telemetry: get: summary: Returns a system's last reported PV Power, Consumption Power, and Battery Power in Watts. Return’s operational mode for Battery, HP, and EVSE description: 'Returns a system''s last reported PV Power, Consumption Power, and Battery Power in Watts. Return’s operational mode for Battery, HP, and EVSE. If the last_report_at is older than 7 days for a specific device, “last_report_at”, “power” and “operational_mode” parameters will be returned in the response with the value as null. PV + Storage sites will always be configured in Net Config. PV only sites can configured either as Net or Total config. For PV only sites configured as Net config (load with solar), consumption power is calculated as: production + grid. For PV only sites configured as Total config, consumption power provided as raw value measured by consumption CT (e.g. the home load). For PV + Storage sites in Net config, consumption power is calculated as production + grid. It does not include battery. Consumption - battery = home load (e.g. fixed load) battery is not considered fixed load, but can contribute to supplying the fixed load. The consumption meter config is available in the /api/v4/system/{system_id}/devices endpoint. Refer to ‘config_type’ parameter. HP Modes: Mode_1 - Blocked Operation Mode_2 - Normal Operation Mode_3 - Power Consumption Recommended Mode_4 - Power Consumption Enforced EVSE Modes: PLUGGED_OUT - EVSE is not plugged in IDLE - EVSE is plugged in but, EV is not charging CHARGING - EVSE is plugged in and EV is charging FAULTED - The EVSE connector is faulted.' tags: - Site Level Consumption Monitoring parameters: - name: system_id in: path description: The unique numeric ID of the system required: true schema: type: integer responses: '200': description: List of devices content: application/json: schema: type: object properties: system_id: type: integer description: System id items: type: string description: The list key 'devices' devices: type: object description: Hash keys include meters, Encharges, heat pumps and EVSEs additionalProperties: type: array items: type: object properties: id: type: integer description: Device ID serial_number: type: string description: Serial number for HP/EVSE devices. name: type: string description: Device Name channel: type: integer description: The reporting channel ID (applicable only in case of meters) last_report_at: type: integer description: Timestamp at which the device last reported power: type: integer description: Power reading at the last reported time operational_mode: type: string description: Battery mode. Possible values are Idle, Charging, Discharging example: system_id: 698943141 items: devices devices: meters: - id: 1084690247 name: production channel: 1 last_report_at: 1701418500 power: 755 - id: 1084690247 name: production channel: 2 last_report_at: null power: null - id: 1084690247 name: production channel: 3 last_report_at: null power: null - id: 1084690248 name: consumption channel: 1 last_report_at: 1701418500 power: 12 - id: 1084690248 name: consumption channel: 2 last_report_at: null power: null - id: 1084690248 name: consumption channel: 3 last_report_at: null power: null encharges: - id: 1084690255 name: Encharge 492205005191 channel: 1 last_report_at: 1701087429 power: -15 operational_mode: Idle - id: 1084690258 name: Encharge 492217007127 channel: 1 last_report_at: 1701418467 power: 0 operational_mode: Idle heat-pump: - serial_number: '' name: Viessmann VitoCal 300G last_report_at: 1757583826 operational_mode: MODE_2 evse: - serial_number: '380699' name: Wallbox last_report_at: 1757583779 operational_mode: PLUGGED_OUT '401': description: Authentication Error content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Authorized details: User is not authorized code: 401 '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Forbidden details: Not authorized to access this resource code: 403 '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Not Found details: System not found for {:id=>"1"} code: 404 '405': description: Method Not Allowed content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '405' message: - Method not allowed '429': description: Too Many Requests content: application/json: schema: type: object properties: message: type: string description: Error Type details: type: string description: Error Details code: type: integer description: Error Code example: message: Too Many Requests details: Usage limit exceeded for plan Kilowatt code: 429 '501': description: Not Implemented content: application/json: schema: type: object properties: reason: type: string message: type: array items: type: string example: reason: '501' message: - Not Implemented