The WebSocket API allows you to receive real time telemetry and device events using Gridshare.

Websocket Endpoints

Connecting to a WebSocket

Use the WebSocket library of your choice to connect to the URL defined above.

Authentication

Use the same Authorization HTTP header that you would use for API requests as described in Authentication.

Realtime Telemetry Streams

You can use the WebSocket connection to receive real-time telemetry data for your devices, and/or the devices of
Lunar customer who have explicitly granted you permission to do so.

To receive telemetry data, you must specify the streams=telemetry-realtime query parameter in the connection URL.

For example:

wss://developer-ws.partner.us.mygridshare?streams=telemetry-realtime

Schedule

Realtime telemetry is sent every 15 minute interval, aligned to the clock (at 0, 15, 30, and 45 minutes past the hour).

Data Format

The format of the telemetry message JSON is:

{
  "stream": "telemetry-realtime",
  "entries": [{
    "kind": "inverter",
    "deviceId": "1234",
    "interval": "2025-10-15T08:30Z/2025-10-15T08:45Z",
    // Other telemetry fields as per the Telemetry API endpoint
  }],
  "telemetryDevices": "partner",
  "interval": "2025-10-15T08:30Z/2025-10-15T08:45Z",
  "telemetryInclude": ["default"]
}

Message delivery

Each message will only contain a limited number of entries so there may be multiple messages for each 15 minute
interval. Note also that different classes of telemetryDevices will be delivered in separate messages.

We will make a best effort to send all the entries for the recently completed 15 minute interval
as soon as possible, but there are no guarantees about ordering of entries or messages.

Receiving Customer Telemetry

By default, when using streams=telemetry-realtime, you will receive telemetry for all devices in your partner account.
It is also possible to receive telemetry for Lunar customers' devices which have explicitly granted you permission to do
so using the publishTo field of the Update Device
API endpoint.

The process is:

1. Use the OAuth flow to request an access token to call the Customer API on the customer's behalf.
   See OAuth Authorization for more details.

   You will need at least the lunar/device.write scope.

2. Call the Update Device
   on the customer's behalf:

   PATCH /api/v1/devices/{synthId}
   Authorization: Bearer <CUSTOMER_ACCESS_TOKEN>
   {
     "publishTo": [{ "clientId": "<YOUR_PARTNER_CLIENT_ID>", "data": ["telemetry-realtime"] }]
   }

   The value <YOUR_PARTNER_CLIENT_ID> is the Client ID you will have been assigned when you registered as a partner.
   The value <CUSTOMER_ACCESS_TOKEN> is the access token you obtained in step 1.

   You must ensure you keep any existing publishTo entries for other partners or applications
   (if any) as this operation replaces the entire publishTo list.

3. Connect to the WebSocket using streams=telemetry-realtime and telemetryDevices=customer

   wss://developer-ws.partner.us.mygridshare.com?streams=telemetry-realtime&telemetryDevices=customer

4. You will now start receiving telemetry for the customer's devices

You can receive both partner and customer telemetry in the same WebSocket connection
by specifying telemetryDevices=partner,customer.

Grid Events

You can use the WebSocket connection to receive real-time events for when a system goes on or off grid.
To receive grid events, you must specify the streams=grid-events query parameter in the connection URL.

For example:

wss://developer-ws.partner.us.mygridshare.com?streams=grid-events

Data Format

The format of the grid event message JSON is:

{
   "stream": "grid-events",  // Always "grid-events"
   "deviceId":"lunar_hc-SIE222200036-gip-XXXXXX", // The device ID
   "timestamp":"2026-04-21T15:46:27.000Z", // The timestamp of the event in ISO 8601 format
   "deviceKind": "meter", // Always "meter
   "state": "not_present" // Or "ok" or "unknown"
}

The state field indicates whether the system is on or off grid. The possible values are:

• ok: The system is on grid
• not_present: The system is off grid
• unknown: The grid state is unknown

Note this schema closely matches the meter device kind in the Telemetry API endpoint
(except without the power fields).

Which devices will send grid events?

Events are sent for all devices you have access to as a Gridshare partner. At the time of writing, customer delegated
devices are not supported, but we may add support for these in the future.

Message delivery

Events are only sent when the status of a device changes. If you need to check the status of a device
historically (e.g. from before you established the WebSocket connection), you can use the following process:

1. Use the Site Topology endpoint to find the device ID of the relevant meter device for the site.
2. Use the Telemetry API endpoint to find the status.

Query Parameter Reference

Ping and Reconnect

After connecting to the WebSocket API, you must:

1. Send a ping message at least every 20 seconds to keep the connection alive
2. Handle disconnects and attempt a reconnect.

See below for examples in JavaScript and Python which handle ping and reconnect.

Code examples

JavaScript (Node.js)

Using the ws library:

import WebSocket from 'ws';

const WS_URL = 'wss://developer-ws.partner.us.mygridshare.com?streams=telemetry-realtime';
const TOKEN = '<PARTNER_ACCESS_TOKEN>';

function connect() {
   const ws = new WebSocket(WS_URL, {
      headers: { Authorization: `Bearer ${TOKEN}` },
   });

   ws.on('message', (data) => {
      console.log('Received data: %s', data);
   });

   const pingTimer = setInterval(() => ws.ping(), 20000);

   ws.on('close', () => {
      clearInterval(pingTimer);
      console.warn('Disconnected. Reconnecting...');
      connect();
   });

   ws.on('error', (err) => {
      console.error('WebSocket error:', err.message);
   });
}

connect();

Python

Using the websocket-client library:

import websocket

def on_message(wsapp, message):
    print(message)

wsapp = websocket.WebSocketApp('wss://developer-ws.partner.us.mygridshare.com?streams=telemetry-realtime',
                               header=['Authorization: Bearer <PARTNER_ACCESS_TOKEN>'],
                               on_message=on_message)
wsapp.run_forever(
   ping_interval=20, 
   ping_timeout=10, 
   reconnect=1 # Wait 1 second before reconnecting
)