Skip to main content

Retrieving Asset Sensor Readings

To retrieve historical sensor readings for one or more assets (irrigation equipment), call the POST /assets/sensor-readings endpoint.

Authenticate your requests with an API key (see Authentication for the Authorization: Api-Key <your_key> header format).

Endpoint​

POST https://api.telaqua.com/assets/sensor-readings

Request​

The request body includes parameters for searching assets:

  • assetIds (UUID array, optional): directly targets assets; when present, other filters are ignored (preferred).
  • assetGroupIds (UUID array, optional): targets assets that belong to one or more asset groups.
  • assetGroupType (enum, optional): asset group type (e.g., FarmBlock).
  • equipmentType (enum or array, optional): equipment types to include (e.g., VALVE, PUMP).

It also includes parameters for filtering sensor readings:

  • from (UTC ISO string, required): start date and time of the query window.
  • to (UTC ISO string, required): end date and time of the query window.
  • limit (positive integer, required, max 200): maximum number of sensor-reading rows to return.
  • lastEvaluatedItem (string, optional): pagination cursor returned by a previous call.

First page example​

{
  "assetIds": [
    "2c37ad05-379b-4823-a105-e1b5e5aab5e6",
    "a5fd205c-56a3-440f-bfa7-fefa88a1ff24"
  ],
  "from": "2025-03-27T00:00:00Z",
  "to": "2025-03-27T23:59:59Z",
  "limit": 100
}

Next page example​

{
  "assetIds": [
    "2c37ad05-379b-4823-a105-e1b5e5aab5e6",
    "a5fd205c-56a3-440f-bfa7-fefa88a1ff24"
  ],
  "from": "2025-03-27T00:00:00Z",
  "to": "2025-03-27T23:59:59Z",
  "limit": 100,
  "lastEvaluatedItem": "ZXhhbXBsZS1iYXNlNjQtY3Vyc29y"
}

Response​

The response is a paginated object:

  • data: array of readings grouped by asset and timestamp.
  • lastEvaluatedItem (optional): cursor to request the next page. If this field is absent in the response, it indicates that there are no further pages.

Each data item contains:

  • id: internal row identifier.
  • time: reading timestamp (UTC).
  • assetId: asset identifier.
  • sensorReadings: array of normalized sensor values for that assetId and time.

Each sensorReadings item contains:

  • name, unit, value, receivedAt
  • optional tagName and tagValue for tagged metrics (for example depth-based probe metrics).
{
  "data": [
    {
      "id": "f31f8f3f-50f0-45b7-8586-39913b3f7e12",
      "time": "2025-03-27T14:51:46Z",
      "assetId": "2c37ad05-379b-4823-a105-e1b5e5aab5e6",
      "sensorReadings": [
        {
          "name": "Pressure",
          "unit": "Pressure",
          "value": 2.5,
          "receivedAt": "2025-03-27T14:51:46Z"
        }
      ]
    },
    {
      "id": "8f2f0639-8e11-4ac0-a6f6-b5c43b520f1a",
      "time": "2025-03-27T14:52:46Z",
      "assetId": "a5fd205c-56a3-440f-bfa7-fefa88a1ff24",
      "sensorReadings": [
        {
          "name": "HumidityByDepth",
          "unit": "Percentage",
          "value": 18.2,
          "tagName": "depth-in-mm",
          "tagValue": 200,
          "receivedAt": "2025-03-27T14:52:46Z"
        }
      ]
    }
  ],
  "lastEvaluatedItem": "ZXhhbXBsZS1uZXh0LXBhZ2UtY3Vyc29y"
}