Retrieve the status of an organization's devices

You can show the status of your devices - whether they are online, in standby mode, or offline. This can indicate whether the devices are actively on the job or parked. Additionally, you can provide the option to view live video from any devices that appear online.


The Surfsight API may take approximately thirty seconds to reflect device status changes.

Device status changes:

  • Devices that are in standby mode get woken up when the vehicle moves, and their status changes to online.

    Device wakeup
  • If your device is connected to a constant power source, the device status changes from online to standby when the vehicle stops moving for up to 60 minutes. The amount of time until your device enters standby mode can be updated with the standby parameter in the PUT /devices/{imei}/device-config call. The default value is 10 minutes.

    No movement
  • If your device is connected to an ignition power source, the device status changes from online to offline when the vehicle is turned off.

    Vehicle off

To show the status of devices, use the following API call in your application and poll the call according to the polling best practices: GET /organizations/{orgId}/devices?limit={limit}&offset={offset}

Parameter Description Example
orgId The ID of the organization. Obtain this from GET /organizations. 3528
limit Set the maximum number of pagination results to receive. 10
offset Set the number of results to skip over before receiving pagination results. 10

We recommend retrieving information by organiztion while using pagination (the limit and offset) in the query parameters to increase performance.

The returned response:

[ data: {
    "imei": "357660101035475",
    "name": "357660101035475",
    "groupId": -1,
    "vehicleType": "Private",
    "cameras": [
        "cameraId": 1,
        "name": "Front Camera"
        "cameraId": 2,
        "name": "Rear Camera"
    "iccid": "899720201470164615",
    "status": "standby",
    "lat": 32.19537996,
    "lon": 34.8839661,
    "alt": 110.69775390625,
    "lastSeenOnline": "2021-12-30T07:49:10.683Z",
    "firmwareVersion": "3.10.13",
    "deviceModel": "AI-12"
  "metadata": {
    "count": 56,
    "limit": 10,
    "offset": 10
Parameter Description Example
imei The IMEI of the device. The IMEI number can be found on a sticker on the device itself or on the back of the device box. 357660101000198
name The name assigned to the device in the POST /organizations/{orgId}/devices call. Harry's truck
groupId The ID of the group with which the device is associated. -1
vehicleType The type of vehicle associated with the device. The type of vehicle affects the sensitivity of the device's motion sensor. Private is the most sensitive to movements, and trailer is the least sensitive. Private
cameras -> cameraId The ID of the camera. 1 - road-facing camera, 2 - in-cabin-facing camera, 50+ - auxiliary cameras. 1
cameras -> name The name assigned to the camera.
iccid The number of the device's SIM card. 899720201470164615
status The device connection status. When online, the device is fully functional. When in standby, the device is connected to the cloud, but live streaming is not available and speed data are not returned. When offline, the device is not connected to the cloud. online
lat The GPS longitude. 32.17380468
lon The GPS latitude. 34.91901649
alt The GPS altitude. 58.77685546875
lastSeenOnline The most recent time that the device connected to the cloud, in ISO 8601 format. Updated every five minutes. 2021-12-14T09:37:57.000Z
firmwareVersion The firmware version of the device. 3.10.6
deviceModel The model of the device. AI-12
metadata -> count The total number of pagination results received. 56
metadata -> limit The maximum number of pagination results to receive. 10
metadata -> offset The number of results to skip over before receiving pagination results. 10

You can show live video from a specific camera by using the ID of that camera.

  • 1: road-facing camera
  • 2: in-cabin camera
  • 50+: auxiliary cameras