Lightbug Documentation

Appearance

Get device readings​

GET
/devices/{id}/readings

Gets readings that a device has taken, such as battery voltage, temperature, humidity etc.

Use filtering to get a specific type.

Filter limitations

When filtering by time ranges, using the timestamp field, you are limited to at most 90 days of data at a time.
If you request more than 90 days, only the latest 90 days in your range will be returned.
A maximum of 10,000 readings can be returned in one request.

Authorizations​

ApiKeyAuth

API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See Authentication for more details.

Type
API Key (header: Authorization)
Example"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Parameters​

Path Parameters

id*

device id

Type
number
Required
Format
"integer"

Query Parameters

filter

JSON Filter object

Type
string
Example{"limit":10,"order":["timestamp DESC"]}{"where":{"type":"temp"},"limit":10,"order":["timestamp DESC"]}{"where":{"type":"temp","timestamp":{"between":["2024-12-01T00:00:00.000Z","2024-12-01T23:59:59.999Z"]}},"order":["timestamp DESC"]}
Format
"JSON"

Request example

Responses​

Request was successful

application/json
JSON
[
  
{
  
  
"timestamp": "string",
  
  
"created": "string",
  
  
"type": "string",
  
  
"value": {
  
  
},
  
  
"rssi": 0,
  
  
"meta": {
  
  
},
  
  
"relatedId": 0,
  
  
"correlationId": "string",
  
  
"id": 0,
  
  
"gatewayId": 0,
  
  
"deviceId": 0,
  
  
"datapointId": 0
  
}
]
Try this endpoint

Playground​

Authorization
Variables
Key
Value

OpenAPI definition ​

References are expanded below, except recursive definitions and references with sibling fields. Documentation overrides are included. Full original OpenAPI spec (JSON).

View endpoint OpenAPI definition
yaml
openapi: 3.1.0
info:
  version: 1.1.0
  title: TrackingAPI
  description: V1 API for retrieving tracking data and changing settings on Lightbug devices
servers:
  - url: https://api.lightbug.cloud/api
externalDocs: {}
security:
  - ApiKeyAuth: []
tags: []
paths:
  /devices/{id}/readings:
    get:
      tags:
        - readings
      summary: Get device readings
      parameters:
        - name: id
          in: path
          description: device id
          required: true
          schema:
            type: number
            format: integer
        - name: filter
          description: JSON Filter object
          in: query
          required: false
          schema:
            type: string
            format: JSON
          example:
            - '{"limit":10,"order":["timestamp DESC"]}'
            - '{"where":{"type":"temp"},"limit":10,"order":["timestamp DESC"]}'
            - '{"where":{"type":"temp","timestamp":{"between":["2024-12-01T00:00:00.000Z","2024-12-01T23:59:59.999Z"]}},"order":["timestamp DESC"]}'
      responses:
'200':
yaml
          description: Request was successful
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    timestamp:
                      description: Timestamp for the reading
                      type: string
                      format: date-time
                    created:
                      description: Timestamp for the writing to db
                      type: string
                      format: date-time
                    type:
                      description: 'Sensor type: ''ultra'' (fill level), ''temp'' (temperature), ...'
                      type: string
                    value:
                      description: JSON value
                      type: object
                    rssi:
                      description: RSSI if from secondary wireless device
                      type: number
                      format: ''
                    meta:
                      description: JSON metadata
                      type: object
                    relatedId:
                      description: LoraId of another (ie for signal strength)
                      type: number
                      format: ''
                    correlationId:
                      description: Internal use - correlation identifier
                      type: string
                    id:
                      type: number
                      format: ''
                    gatewayId:
                      type: number
                      format: ''
                    deviceId:
                      type: number
                      format: ''
                    datapointId:
                      type: number
                      format: ''
                  required:
                    - timestamp
                    - created
                    - type
                    - value
                  type: object
yaml
      deprecated: false
      security:
        - ApiKeyAuth: []
      operationId: get-devices-id-readings
      description: |-
        Gets [readings](/terminology/readings) that a device has taken, such as battery voltage, temperature, humidity etc.

        Use [filtering](/apis/v1/filtering) to get a specific [type](/terminology/readings#types).

        ### Filter limitations

        When filtering by time ranges, using the `timestamp` field, you are limited to at most 90 days of data at a time.
        If you request more than 90 days, only the latest 90 days in your range will be returned.
        A maximum of 10,000 readings can be returned in one request.
components:
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
      description: API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See <a href='/apis/authentication'>Authentication</a> for more details.
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...