# Sensors

Sensor data and metadata retrieval

## Get sensors with calibration data, latest measurements, and alert settings

> Fetches the list of claimed and shared sensors with calibration data, sensor\
> last measurement, subscription type and alert settings.\
> \
> By default the endpoint returns only the claimed sensors with calibration\
> data. Optional query parameters must be passed to get shared sensors,\
> last measurements, and alert settings.<br>

```json
{"openapi":"3.0.3","info":{"title":"Ruuvi Cloud - User API","version":"1.0.0"},"tags":[{"name":"Sensors","description":"Sensor data and metadata retrieval"}],"servers":[{"url":"https://network.ruuvi.com"},{"url":"https://testnet.ruuvi.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Success":{"type":"object","required":["result","data"],"properties":{"result":{"type":"string","enum":["success"]},"data":{"description":"Endpoint-specific payload"}}},"SensorBase":{"type":"object","required":["owner","sensor","name","public","canShare","offsetTemperature","offsetHumidity","offsetPressure","customProfile","lastUpdated"],"properties":{"owner":{"type":"string","format":"email"},"sensor":{"type":"string","description":"MAC address of the sensor"},"name":{"type":"string"},"picture":{"type":"string","maxLength":2048},"public":{"type":"boolean"},"canShare":{"type":"boolean"},"offsetTemperature":{"type":"number","format":"float"},"offsetHumidity":{"type":"number","format":"float"},"offsetPressure":{"type":"number","format":"float"},"customProfile":{"type":"boolean"},"lastUpdated":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the sensor or its profile was last updated (whichever is more recent).\n"}}},"SensorMeasurement":{"type":"object","required":["gwmac","coordinates","rssi","timestamp","data"],"properties":{"gwmac":{"type":"string","description":"MAC address of the gateway that received this measurement","pattern":"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"},"coordinates":{"type":"string","description":"GPS coordinates of the gateway, or \"N/A\" if unavailable"},"rssi":{"type":"integer","description":"Received Signal Strength Indicator in dBm"},"timestamp":{"type":"integer","format":"int64","description":"Unix epoch timestamp in seconds when the measurement was recorded"},"data":{"type":"string","description":"Hex-encoded raw sensor data payload"}}},"Subscription":{"type":"object","required":["subscriptionName","maxClaims","maxShares","maxSharesPerSensor","maxHistoryDays","maxResolutionMinutes","emailAlertAllowed","pushAlertAllowed","telegramAlertAllowed","delayedAlertAllowed","pdfExportAllowed","offlineAlertAllowed","isActive","startTime","endTime","endAt","lastUpdated"],"properties":{"subscriptionName":{"type":"string"},"maxClaims":{"type":"integer"},"maxShares":{"type":"integer"},"maxSharesPerSensor":{"type":"integer"},"maxHistoryDays":{"type":"integer"},"maxResolutionMinutes":{"type":"integer"},"emailAlertAllowed":{"type":"boolean"},"pushAlertAllowed":{"type":"boolean"},"telegramAlertAllowed":{"type":"boolean"},"delayedAlertAllowed":{"type":"boolean"},"pdfExportAllowed":{"type":"boolean"},"offlineAlertAllowed":{"type":"boolean"},"isActive":{"type":"boolean"},"startTime":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the subscription started."},"endTime":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the subscription ends."},"endAt":{"type":"string","format":"date-time"},"lastUpdated":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the subscription was last updated. If missing, it is assumed to be the current time.\n"}}},"Alert":{"type":"object","required":["type","min","max","counter","delay","enabled","description","triggered","lastUpdated"],"properties":{"type":{"$ref":"#/components/schemas/AlertType"},"min":{"type":"number","format":"double","description":"Lower limit for the alert condition"},"max":{"type":"number","format":"double","description":"Upper limit for the alert condition"},"counter":{"type":"integer","description":"Movement counter threshold (relevant for movement type alerts)"},"delay":{"type":"integer","description":"Delay in minutes before triggering the alert"},"enabled":{"type":"boolean","description":"Whether the alert is active"},"description":{"type":"string","description":"User-provided description of the alert"},"triggered":{"type":"boolean","description":"Whether the alert has been triggered"},"triggeredAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the alert was triggered. '1970-01-01T00:00:00.000Z' indicates the alert has never been triggered"},"lastUpdated":{"type":"integer","format":"int64","description":"Epoch timestamp in seconds when the alert was last updated"}}},"AlertType":{"type":"string","enum":["temperature","pressure","humidity","humidityAbsolute","dewPoint","signal","movement","battery","offline","luminosity","voc","co2","sound","soundInstant","soundAverage","soundPeak","nox","pm10","pm25","pm40","pm100","aqi"],"description":"Type of alert condition"},"SettingObject":{"type":"object","description":"Sensor settings as flattened key-value pairs.\n- Setting values are stored with keys matching the setting type name.\n- Each setting has a corresponding `{settingName}_lastUpdated` field containing an epoch timestamp.\n- Up to 500 setting pairs (1000 total properties including timestamps).\n- Setting values are strings (max 1000 chars), timestamp fields are integers (epoch seconds).\n\n\n**Property patterns:**\n- Pattern `^(?!.*_lastUpdated$).+$`: Setting value\n- Pattern `^.+_lastUpdated$`: Epoch timestamp in seconds for when the setting was last updated","maxProperties":1000,"additionalProperties":{"oneOf":[{"type":"string","maxLength":1000,"description":"Setting value (matches pattern: ^(?!.*_lastUpdated$).+$)"},{"type":"integer","format":"int64","description":"Epoch timestamp in seconds for when the setting was last updated (matches pattern: ^.+_lastUpdated$)"}]}},"Error":{"type":"object","required":["result","error","code"],"properties":{"result":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable explanation"},"code":{"type":"string","description":"Machine-readable primary error code"},"sub_code":{"nullable":true,"type":"string","description":"Optional secondary code useful for client logic"}}}}},"paths":{"/sensors-dense":{"get":{"summary":"Get sensors with calibration data, latest measurements, and alert settings","description":"Fetches the list of claimed and shared sensors with calibration data, sensor\nlast measurement, subscription type and alert settings.\n\nBy default the endpoint returns only the claimed sensors with calibration\ndata. Optional query parameters must be passed to get shared sensors,\nlast measurements, and alert settings.\n","operationId":"getSensorsDense","tags":["Sensors"],"parameters":[{"name":"sensor","in":"query","required":false,"schema":{"type":"string","pattern":"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"},"description":"Optionally filter results to a single sensor by MAC address"},{"name":"sharedToOthers","in":"query","required":false,"schema":{"type":"boolean"},"description":"If true, each sensor object includes the list of users it is shared to. Returns an empty list for sensors the caller does not own.\n"},{"name":"sharedToMe","in":"query","required":false,"schema":{"type":"boolean"},"description":"If true, sensors that are shared to the logged-in user are included in the response alongside sensors claimed by the user.\n"},{"name":"measurements","in":"query","required":false,"schema":{"type":"boolean"},"description":"If true, the latest measurement for each sensor is included. Also returns the active subscription details for each sensor.\n"},{"name":"alerts","in":"query","required":false,"schema":{"type":"boolean"},"description":"If true, the alert settings for each sensor are included.\n"},{"name":"settings","in":"query","required":false,"schema":{"type":"boolean"},"description":"If true, sensor-specific settings are included for each sensor.\n"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["dense","sparse","mixed"],"default":"mixed"},"description":"Fetch mode for measurement data. `dense` returns highest data density for a limited time range. `sparse` returns downsampled data with no time-range limit. `mixed` returns all dense data available and fills the rest with sparse data. Default: `mixed`.\n"}],"responses":{"200":{"description":"Sensors retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Success"},{"type":"object","properties":{"data":{"type":"object","required":["sensors"],"properties":{"sensors":{"type":"array","description":"List of sensors the caller has claimed, and optionally sensors shared to them","items":{"allOf":[{"$ref":"#/components/schemas/SensorBase"},{"type":"object","properties":{"owner":{"type":"string","format":"email","description":"Email address of the sensor owner. Partially masked when the sensor is public and the caller does not own it.\n"},"sharedTo":{"type":"array","description":"Email addresses of users this sensor is shared to. Present when `sharedToOthers=true`.\n","items":{"type":"string","format":"email"}},"measurements":{"type":"array","description":"Latest measurement(s) received from the sensor. Present when `measurements=true`.\n","items":{"$ref":"#/components/schemas/SensorMeasurement"}},"subscription":{"allOf":[{"$ref":"#/components/schemas/Subscription"},{"description":"Active subscription details for this sensor. Present when `measurements=true`.\n"}]},"alerts":{"type":"array","description":"Alert settings configured for this sensor. Present when `alerts=true`.\n","items":{"$ref":"#/components/schemas/Alert"}},"settings":{"allOf":[{"$ref":"#/components/schemas/SettingObject"},{"description":"Sensor-specific settings as flattened key-value pairs. Present when `settings=true`.\n"}]}}}]}}}}}}]}}}},"401":{"description":"UNAUTHORIZED - Auth token missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN - Sensor exists but caller does not have access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```