> For the complete documentation index, see [llms.txt](https://docs.ruuvi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ruuvi.com/communicate-with-ruuvi-cloud/cloud/user-api/sensors.md).

# Sensors

Sensor data and metadata retrieval

## Get sensor measurements and history limits

> Returns sensor metadata, measurements, and the effective history and\
> resolution limits used for the query.\
> \
> Public sensors can be read without authentication. Private sensors require\
> authentication as the owner or a user the sensor is shared with. When an\
> Authorization header is supplied, it must be valid, even for public sensors.\
> \
> History and resolution limits come from the sensor owner's subscription,\
> including for anonymous callers and authenticated callers with a different\
> subscription. Clients can request \`limit=1\` to fetch the latest measurement\
> and these limits before deciding whether to show history controls.\
> \`maxHistoryDays=0\` means history is unavailable. Positive values describe the\
> allowed lookback window, not the actual span of recorded measurements.\
> An empty measurements array does not change these limits.\
> \
> Anonymous requests are rate limited to 5 per minute per sensor and source\
> IP, in addition to the shared anonymous limit of 60 per minute per source IP.<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":{"SensorDataResponse":{"allOf":[{"$ref":"#/components/schemas/Success"},{"type":"object","properties":{"data":{"type":"object","required":["sensor","name","offsetTemperature","offsetHumidity","offsetPressure","picture","measurements","total","public","maxHistoryDays","maxResolutionMinutes"],"properties":{"sensor":{"type":"string","description":"MAC address of the sensor","pattern":"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"},"name":{"type":"string"},"offsetTemperature":{"type":"number"},"offsetHumidity":{"type":"number"},"offsetPressure":{"type":"number"},"picture":{"type":"string","description":"Sensor picture URL, or an empty string if no picture is set"},"measurements":{"type":"array","items":{"$ref":"#/components/schemas/SensorMeasurement"}},"total":{"type":"integer","minimum":0,"description":"Number of measurements returned in this response"},"public":{"type":"boolean","description":"Whether the sensor is publicly readable"},"maxHistoryDays":{"type":"integer","minimum":0,"description":"Maximum history window in days allowed by the sensor owner's subscription, using the same validated limit as the measurement query. Applies to anonymous and authenticated callers alike. Zero means history is unavailable and at most one measurement is returned. A positive value allows history controls up to this window, but does not guarantee that measurements exist throughout it. This is an access limit, not the age of the oldest stored measurement. Returned even when measurements is empty or limit=1.\n"},"maxResolutionMinutes":{"type":"integer","minimum":1,"description":"Measurement resolution limit in minutes from the sensor owner's subscription, using the same validated value as the measurement query. One allows the highest available resolution. Data can be sparser because of the selected mode, storage downsampling, or missing measurements. Returned even when measurements is empty or limit=1.\n"}}}}}]},"Success":{"type":"object","required":["result","data"],"properties":{"result":{"type":"string","enum":["success"]},"data":{"description":"Endpoint-specific payload"}}},"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"}}},"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":{"/get":{"get":{"summary":"Get sensor measurements and history limits","description":"Returns sensor metadata, measurements, and the effective history and\nresolution limits used for the query.\n\nPublic sensors can be read without authentication. Private sensors require\nauthentication as the owner or a user the sensor is shared with. When an\nAuthorization header is supplied, it must be valid, even for public sensors.\n\nHistory and resolution limits come from the sensor owner's subscription,\nincluding for anonymous callers and authenticated callers with a different\nsubscription. Clients can request `limit=1` to fetch the latest measurement\nand these limits before deciding whether to show history controls.\n`maxHistoryDays=0` means history is unavailable. Positive values describe the\nallowed lookback window, not the actual span of recorded measurements.\nAn empty measurements array does not change these limits.\n\nAnonymous requests are rate limited to 5 per minute per sensor and source\nIP, in addition to the shared anonymous limit of 60 per minute per source IP.\n","operationId":"getSensorData","tags":["Sensors"],"parameters":[{"name":"sensor","in":"query","required":true,"description":"MAC address of the sensor","schema":{"type":"string","pattern":"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"}},{"name":"since","in":"query","required":false,"description":"Start time as Unix epoch seconds. History queries are limited to the owner's allowed history window. Defaults to the start of that window. When only one measurement is fetched, the history window is ignored so the latest measurement can be returned even if it is older.\n","schema":{"type":"integer","format":"int64"}},{"name":"until","in":"query","required":false,"description":"End time as Unix epoch seconds. Defaults to the current time.","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of measurements to return. Values above 144000 are capped. When maxHistoryDays is zero, at most one measurement is returned regardless of this parameter.\n","schema":{"type":"integer","minimum":1,"default":15}},{"name":"sort","in":"query","required":false,"description":"Sort measurements by timestamp, newest first by default.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"mode","in":"query","required":false,"description":"Fetch mode for measurements. Dense returns recent high resolution data, sparse returns downsampled data, and mixed combines both. Every mode is subject to the owner's history and resolution limits.\n","schema":{"type":"string","enum":["dense","sparse","mixed"],"default":"mixed"}}],"responses":{"200":{"description":"Sensor measurements and history limits retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SensorDataResponse"}}}},"400":{"description":"Invalid sensor or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Supplied authentication is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sensor was not found or the caller does not have access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## 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"}}}}}}}}}
```
