openapi: 3.0.0 info: title: The Enlighten Systems Device Level Production Monitoring Site Level Consumption Monitoring API description: 'The Enlighten Systems API is a JSON-based API that provides access to performance data for a PV system. By using the Enlighten Systems API, you agree to the Enphase Energy API License Agreement. Please note that the Enlighten Systems API does not provide performance data at a panel or microinverter level.' version: '2.0' termsOfService: https://developer.enphase.com/docs#Display-Requirements license: name: Enphase API License Agreement url: https://www.enphase.com/en-us/legal/api-license-agreement servers: - url: https://api.enphaseenergy.com/api/v2 security: - ApiKey: [] tags: - name: Site Level Consumption Monitoring paths: /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." operationId: getConsumptionLifetime 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. 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. examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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. operationId: getBatteryLifetime 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. 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. examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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. operationId: getEnergyImportLifetime 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. 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. examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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. operationId: getEnergyExportLifetime 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. 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. examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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." operationId: getBatteryTelemetry 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: $ref: '#/components/schemas/TelemetryGranularity' 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: allOf: - $ref: '#/components/schemas/TelemetryGranularity' 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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." operationId: getConsumptionMeterTelemetry 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: $ref: '#/components/schemas/TelemetryGranularity' 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: allOf: - $ref: '#/components/schemas/TelemetryGranularity' 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. examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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.' operationId: getEnergyImportTelemetry 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: $ref: '#/components/schemas/TelemetryGranularity' 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: allOf: - $ref: '#/components/schemas/TelemetryGranularity' 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 description: Telemetry readings grouped by device and channel. items: type: object properties: end_at: type: integer description: End time of the telemetry interval wh_imported: 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. examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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.' operationId: getEnergyExportTelemetry 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: $ref: '#/components/schemas/TelemetryGranularity' 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: allOf: - $ref: '#/components/schemas/TelemetryGranularity' 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. examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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. description: Returns a system's last reported PV Power, Consumption Power, and Battery Power in Watts. 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. operationId: getLatestSystemTelemetry 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, and Encharges additionalProperties: type: array items: type: object properties: id: type: integer description: Device ID 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 nullable: true description: Timestamp at which the device last reported power: type: integer nullable: true description: Power reading at the last reported time operational_mode: type: string description: Battery mode. Possible values are Idle, Charging, Discharging examples: response: value: 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 '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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: 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 examples: response: value: reason: '501' message: - Not Implemented components: schemas: TelemetryGranularity: type: string description: Interval size used when returning telemetry time series. enum: - 5mins - 15mins - day - week securitySchemes: ApiKey: type: apiKey name: key in: query