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

Websocket Endpoints

	WebSocket Endpoint
Production (USA)	wss://developer-ws.partner.us.mygridshare.com
Production (rest of world)	Coming soon!
Development (USA)	wss://developer-ws.partner.dev0.us.mygridshare.com
Development (rest of world)	Coming soon!

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"]
}

Field	Description
stream	The stream of data, which is always `telemetry-realtime`
entries	The actual telemetry entries. Follows the same definition as the Telemetry API endpoint
telemetryDevices	Indicates whether this telemetry is for your partner devices (`partner`) or customer devices (`customer`)
telemetryInclude	Which fields were requested (see Query Parameter Reference below)
interval	The ISO 8601 interval of the recently completed 15 minute period

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:

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.
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.

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

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

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:

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

Query Parameter Reference

Parameter	Description	Required	Default value
streams	Comma-separated list of data streams to receive. Supported streams: `telemetry-realtime`, `grid-event`	Yes
telemetryDevices	Comma-separated list of what to receive when using `streams=telemetry-realtime`. Use `partner` to receive telemetry for all devices in your partner account. Or, `customer` to receive customer telemetry (requires an explicit `publishTo`)	No	partner
telemetryInclude	Comma-separated list of what fields to include when using `streams=telemetry-realtime`. E.g., `default,energy`. Follows the same pattern as the `include` query paramater in the Telemetry API endpoint		No

Ping and Reconnect

After connecting to the WebSocket API, you must:

Send a ping message at least every 20 seconds to keep the connection alive
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
)