Skip to main content

Site Telemetry

1. Getting Started​

The Site Telemetry endpoint provides time-series energy data for Generac-monitored sites. Typical integrations use it to stream live readings, pull historical data for reporting, or fetch the most recent system snapshot. This section walks through each use case with practical guidance on how to structure your requests.

1.1 Streaming Current Telemetry​

For applications that need a continuous feed of telemetry — dashboards, alerting pipelines, or data warehouses — set up a polling job that runs periodically. Telemetry records are every 5 minutes, so polling once a minute is not recommended as its unnecessary. Each cycle should issue one or more requests:

Fetch new data. Set startTime to the endTime of the last record you received, and endTime to the current time (or slightly into the future). This captures any records generated since your last poll.

Because both edges of the query interval are exclusive, aligning your boundaries to existing record timestamps avoids duplicates and makes stitching seamless.

Example: Incremental Poll​

Your last stored record covers 14:10:00–14:15:00. Your next request:

GET /v1/sites/{siteId}/telemetry
    ?startTime=2025-12-01T14:15:00Z
    &endTime=2025-12-01T14:20:00Z

The 14:10–14:15 record will not be returned again because its endTime does not fall within the exclusive query window.

1.2 Fetching Historical Telemetry​

Fill gaps. If you detect a gap between stored records, request the missing interval. Set startTime to the endTime of the record before the gap, and endTime to the startTime of the first record after the gap. Maximum query range is 24 hours. Exceeding this returns a 400 Bad Request.

To pull a full day of data, query from midnight to midnight:

GET /v1/sites/{siteId}/telemetry
    ?startTime=2025-12-01T00:00:00Z
    &endTime=2025-12-02T00:00:00Z

Since the system's records are typically clock-aligned (typical for Generac systems), you'll get exactly the records for that calendar day. For some telemetry records the timestamp may not be clock aligned and you may receive an extra record on each edge where a record partially overlaps the boundary. These partial-overlap records can be identified by comparing their timestamps to your query window and be filtered out or deduplicated as needed.

The maximum query range is 24 hours. For multi-day retrieval, issue one request per day.

1.3 Getting the Most Recent Value​

To fetch a current reading — for example, to display a live status card — request a padded interval around the current time and take the last record in the response:

GET /v1/sites/{siteId}/telemetry
    ?startTime=2025-12-01T11:45:00Z   // ~15 min ago
    &endTime=2025-12-01T12:15:00Z     // ~15 min from now

The padding accounts for variable record timing and the fact that the most recent record may still be in progress. The last element of the response array is your freshest data point.

2. Reference​

2.1 Interval Matching​

A telemetry record is returned if it overlaps with the query window. Both boundaries are strict — a record that only touches the query interval without overlapping is excluded.

Matching Rule

record.startTime < query.endTime  AND  record.endTime > query.startTime

Visual Example

Records at 5-minute intervals, queried from 00:10 to 00:25:

Records:  |00:00-00:05|00:05-00:10|00:10-00:15|00:15-00:20|00:20-00:25|00:25-00:30|
Query:                            (00:10 ======================= 00:25)

Returned:                         |00:10-00:15|00:15-00:20|00:20-00:25|

✗ 00:05-00:10  → endTime (00:10) is not > query startTime (00:10)
✗ 00:25-00:30  → startTime (00:25) is not < query endTime (00:25)

2.2 Query Window Quick Reference​

Use CasestartTimeendTimeTake
Stream / PollendTime of last recordNow (or slightly future)All records
Fill GapendTime of record before gapstartTime of record after gapAll records
Historical DayDay start (midnight)Next day (midnight)All records
Latest Value~15 min ago~15 min from nowLast record

2.3 Response Structure​

Each record in the response data array covers a discrete time interval and includes measurement groups depending on the site's equipment:

FieldDescription
startTimeStart of the record interval (ISO 8601)
endTimeEnd of the record interval (ISO 8601)
gridImport/export energy & power, connectivity status. Null if N/A.
solarSolar production energy & power. Null if N/A.
consumptionLoad energy & power. Null if N/A.
storageBattery charge/discharge, state of charge, reserve. Null if N/A.
  • Energy values are in watt-hours. Power values are in watts, averaged over the record interval.
  • Signed fields: for grid and storage, positive = import/discharge, negative = export/charge.
  • State of charge and minimum reserve are percentages out of 100.
  • Lifetime counters are cumulative and monotonically increasing, reflecting totals as of the record's end.

2.4 Constraints & Notes​

  • Maximum query range is 24 hours. Exceeding this returns a 400 Bad Request.
  • Timestamps must be ISO 8601 with offset (UTC recommended, e.g. 2025-12-01T00:00:00Z).
  • Records are typically 5 minutes in duration, but this is not guaranteed. Always use startTime and endTime on each record rather than assuming a fixed interval.
  • Measurement groups are null when the corresponding equipment is not present at the site.