Events

Subscribe to discrete events published by devices in real time. Events are user-defined moments like "door opened", "boot complete", or "geofence entered" — see the Device SDK Event module for the publishing side.

Access via app.events.

API

stream()

Subscribe to events by name.

JavaScript

app.events.stream(params)

Python

await app.events.stream(params)

Parameter	Type	Description
name	string	The event name to subscribe to
callback	function	Called with each incoming event payload

Returns true if the subscription was created, false if already subscribed to that event name

JavaScript

app.events.stream({
  name: "door_opened",
  callback: (data) => {
    console.log("Door event:", data);
  },
});

Python

await app.events.stream({
    "name": "door_opened",
    "callback": lambda data: print("Door event:", data),
})

The callback receives an object with value (the payload the device sent via device.event.send()) and timestamp (a Unix timestamp of when the event was published).

Example callback data:

{
  "value": {
    "door": "front",
    "method": "keycard"
  },
  "timestamp": 1743292800000
}

{
  "value": {
    "zone": "warehouse-A",
    "lat": 40.7128,
    "lng": -74.006
  },
  "timestamp": 1743292860000
}

off()

Unsubscribe from an event.

JavaScript

app.events.off(params)

Python

await app.events.off(params)

Parameter	Type	Description
name	string	The event name to unsubscribe from

JavaScript

app.events.off({ name: "door_opened" });

Python

await app.events.off({"name": "door_opened"})

history()

Query historical events for a device over a time range.

JavaScript

await app.events.history(params)

Python

await app.events.history(params)

Parameter	Type	Description
device_ident	string	The device identifier
event_names	string[]	Event names to query
start	string	Start time (ISO 8601, UTC)
end	string	End time (ISO 8601, UTC)

Returns an object keyed by event name, each containing an array of entries.

JavaScript

const events = await app.events.history({
  device_ident: "sensor_01",
  event_names: ["door_opened", "door_closed"],
  start: "2026-01-01T00:00:00.000Z",
  end: "2026-01-08T00:00:00.000Z",
});

events.door_opened.forEach((entry) => {
  console.log(`${entry.timestamp}:`, entry.value);
});

Python

events = await app.events.history({
    "device_ident": "sensor_01",
    "event_names": ["door_opened", "door_closed"],
    "start": "2026-01-01T00:00:00.000Z",
    "end": "2026-01-08T00:00:00.000Z",
})

for entry in events["door_opened"]:
    print(f"{entry['timestamp']}: {entry['value']}")

Example response:

{
  "door_opened": [
    { "value": { "door": "front", "method": "keycard" }, "timestamp": 1774690200000 },
    { "value": { "door": "front", "method": "keycard" }, "timestamp": 1774690800000 }
  ],
  "door_closed": [
    { "value": { "door": "front" }, "timestamp": 1774690260000 }
  ]
}

Event names you requested but that have no data in the range are still included as empty arrays.

History retention

History retention depends on your plan. Queries outside your retention window will return empty arrays.