Access Proxy Data Trough API

Get Device Proxy Configurations

Returns the proxy configurations assigned to a device, including the resolved proxy template definition when requested through the include filter.

Endpoint

GET /devices/{deviceId}/getProxyConfigs

Example Request

curl --location 'https://api.whysor.com/devices/2e02f567-2071-48db-af54-5665e3645c82/getProxyConfigs?filter=%7B%22include%22%3A%22proxyConfigTemplate%22%7D' \
  --header 'authorization: <token>' \
  --header 'Accept: application/json, text/plain, */*'

Query Parameters

Parameter	Type	Description
`filter.include`	string	Includes related entities in the response. Use `proxyConfigTemplate` to retrieve the full template definition alongside the configuration instance.

Example:

{
  "include": "proxyConfigTemplate"
}

Response

Returns an array of proxy configuration instances assigned to the device.

[
  {
    "id": "4904c69f-711e-45a7-8231-25dcddde8a4e",
    "proxyConfigTemplateId": "40e87644-f77f-4014-a27c-294492b34e3c",
    "deviceIds": [
      "2e02f567-2071-48db-af54-5665e3645c82"
    ],
    "configuration": {},
    "proxyConfigTemplate": {}
  }
]

How It Works

A proxy configuration connects one or more device sensors to a processing module (proxy) that generates derived sensor values.

In this example, the device is configured to run the Watermappers - Groundwater Level Calculation proxy.

The proxy:

Reads raw pressure measurements from the device.
Maps those measurements to the expected proxy inputs.
Applies configuration parameters.
Sends the data to the proxy module.
Produces calculated output sensors such as groundwater level.

Input Sensor Mapping

The configuration instance maps actual device sensors to the logical inputs expected by the template.

Template Definition

The template expects:

{
  "externalName": "pressure_submerged",
  "tag": "pressure"
},
{
  "externalName": "pressure_air",
  "tag": "pressure_reference"
}

Device Mapping

The device assigns concrete sensors:

{
  "sensorId": "90ab7921-d001-4b4d-a6af-29152767ea1a",
  "externalName": "pressure_submerged"
},
{
  "sensorId": "d931da38-1377-4c43-96d3-c24a68560f20",
  "externalName": "pressure_air"
}

Result

Sensor ID	Mapped As	Proxy Input
`90ab7921-d001-4b4d-a6af-29152767ea1a`	`pressure_submerged`	Water pressure sensor
`d931da38-1377-4c43-96d3-c24a68560f20`	`pressure_air`	Atmospheric reference pressure

Output Sensors

The proxy generates three derived measurements.

[
  {
    "tag": "groundwater_level"
  },
  {
    "tag": "sensor_level"
  },
  {
    "tag": "water_column"
  }
]

Output Tag	Description
`groundwater_level`	Calculated groundwater elevation relative to sea level.
`sensor_level`	Calculated elevation of the submerged sensor.
`water_column`	Water column above the sensor derived from pressure difference.

All three outputs are written using sensor template:

faef88aa-35e5-4658-9a73-f3bebd00fadc

Parameters

The template defines a set of configurable parameters.

Template Schema

[
  {
    "key": "elevation",
    "type": "number"
  },
  {
    "key": "pipe_height",
    "type": "number"
  },
  {
    "key": "pipe_length",
    "type": "number"
  },
  {
    "key": "cable_length",
    "type": "number"
  },
  {
    "key": "reversed",
    "type": "boolean"
  }
]

Configured Values

{
  "elevation": 575,
  "pipe_height": 0.4,
  "pipe_length": 66,
  "cable_length": 17.8,
  "reversed": true
}

Parameter	Value	Description
`elevation`	`575`	Ground elevation above sea level (m).
`pipe_height`	`0.4`	Height of casing above ground (m).
`pipe_length`	`66`	Total monitoring pipe length (m).
`cable_length`	`17.8`	Distance from casing top to sensor (m).
`reversed`	`true`	Indicates pressure values should be inverted before calculation.

Processing Flow

Device Sensors
│
├─ pressure_submerged
└─ pressure_air
        │
        ▼
Sensor Mapping
        │
        ▼
Groundwater Level Proxy
(Module: 5ea64918-0acc-401f-8abf-8f7e4ccbeee3)
        │
        ▼
Calculation Engine (/infer/)
        │
        ▼
Generated Sensors
├─ groundwater_level
├─ sensor_level
└─ water_column

List Proxy Sensors

Returns all proxy sensors associated with a device.

Proxy sensors are virtual sensors created by a proxy configuration. They store calculated values rather than measurements directly received from hardware sensors.

Endpoint

GET /proxysensors

Example Request

curl --location --globoff 'https://api.whysor.com/proxysensors?filter[where][deviceId]=2e02f567-2071-48db-af54-5665e3645c82' \
  --header 'Authorization: <token>' \
  --header 'Content-Type: application/json'

Query Parameters

This endpoint follows the standard sensor listing conventions and supports the same LoopBack filtering structure used throughout the API.

Example Filter

GET /proxysensors?filter[where][deviceId]=2e02f567-2071-48db-af54-5665e3645c82

Returns all proxy sensors belonging to the specified device.

Response

[
  {
    "id": "36c293d6-0c17-4f31-9cd8-ca99a204a2e2",
    "tag": "water_column",
    "deviceId": "2e02f567-2071-48db-af54-5665e3645c82",
    "proxyConfigId": "4904c69f-711e-45a7-8231-25dcddde8a4e"
  },
  {
    "id": "97a2ffb4-fe83-48f7-9e2c-45ca0b0b3c7d",
    "tag": "sensor_level",
    "deviceId": "2e02f567-2071-48db-af54-5665e3645c82",
    "proxyConfigId": "4904c69f-711e-45a7-8231-25dcddde8a4e"
  },
  {
    "id": "d778ccb1-1e8e-419f-aafc-8411367b27a6",
    "tag": "groundwater_level",
    "deviceId": "2e02f567-2071-48db-af54-5665e3645c82",
    "proxyConfigId": "4904c69f-711e-45a7-8231-25dcddde8a4e"
  }
]

Response Fields

Field	Type	Description
`id`	string	Unique proxy sensor identifier.
`name`	string	Human-readable sensor name. May be empty.
`description`	string	Sensor description. May be empty.
`tag`	string	Logical output tag defined by the proxy configuration.
`deviceId`	string	Device that owns the proxy sensor.
`proxyConfigId`	string	Proxy configuration that generates this sensor.
`sensorTemplateId`	string	Template describing the sensor type and metadata.
`additionalInfo`	object	Additional sensor metadata.
`created`	datetime	Creation timestamp (UTC).
`modified`	datetime	Last modification timestamp (UTC).

Example Result

For device:

2e02f567-2071-48db-af54-5665e3645c82

the API returns three generated sensors:

Proxy Sensor ID	Tag	Description
`d778ccb1-1e8e-419f-aafc-8411367b27a6`	`groundwater_level`	Calculated groundwater elevation.
`97a2ffb4-fe83-48f7-9e2c-45ca0b0b3c7d`	`sensor_level`	Calculated elevation of the submerged sensor.
`36c293d6-0c17-4f31-9cd8-ca99a204a2e2`	`water_column`	Calculated water column height.

All three sensors are generated by proxy configuration:

4904c69f-711e-45a7-8231-25dcddde8a4e

and use sensor template:

faef88aa-35e5-4658-9a73-f3bebd00fadc

Relationship to Proxy Configurations

The proxy sensors returned by this endpoint correspond directly to the output mappings defined in the device's proxy configuration.

Example:

{
  "tag": "groundwater_level"
},
{
  "tag": "sensor_level"
},
{
  "tag": "water_column"
}

Each configured output results in a dedicated proxy sensor record that can subsequently be queried using:

GET /proxysensors/{proxySensorId}/read

For example:

GET /proxysensors/d778ccb1-1e8e-419f-aafc-8411367b27a6/read

Read Proxy Sensor Values

Reads measurement data from a proxy sensor.

Proxy sensors are virtual sensors whose values are generated by a proxy calculation rather than being directly measured by a physical device. Examples include groundwater level, water column, or other derived measurements generated through a proxy configuration.

Endpoint

GET /proxysensors/{proxySensorId}/read

Example Request

curl --location 'https://api.whysor.com/proxysensors/d778ccb1-1e8e-419f-aafc-8411367b27a6/read' \
  --header 'Authorization: <token>' \
  --header 'Content-Type: application/json'

Response

[
  {
    "sensorId": "d778ccb1-1e8e-419f-aafc-8411367b27a6",
    "datetimeMeasure": "2026-11-09T13:13:33Z",
    "value": 562.127539985622
  }
]

Response Fields

Field	Type	Description
`sensorId`	string	Identifier of the proxy sensor.
`datetimeMeasure`	datetime	Timestamp of the measurement in UTC.
`value`	number	Calculated sensor value at the specified timestamp.

For the example above:

{
  "sensorId": "d778ccb1-1e8e-419f-aafc-8411367b27a6",
  "datetimeMeasure": "2026-11-09T13:13:33Z",
  "value": 562.127539985622
}

This indicates that the proxy sensor produced a calculated value of 562.127539985622 at 2026-11-09T13:13:33Z.

Query Parameters

The proxy sensor read endpoint supports the same filtering, pagination, aggregation, and time-range options as the standard sensor read endpoint.

In practice, any query parameters supported by:

GET /sensor/{sensorId}/read

are also supported by:

GET /proxysensors/{proxySensorId}/read

This includes, but is not limited to:

Time range filtering (where.datetimeMeasure)
Ordering (order)
Limiting (limit)
Skipping records (skip)

How It Works

Physical Sensors
       │
       ▼
Proxy Calculation
       │
       ▼
Proxy Sensor
(d778ccb1-1e8e-419f-aafc-8411367b27a6)
       │
       ▼
/proxysensors/{id}/read

Unlike a regular sensor, a proxy sensor stores values that are generated by a calculation module. Once generated, the resulting time series can be queried exactly like a normal sensor time series.

This means clients can use the same read logic, filtering, aggregation, dashboards, and visualizations for both physical sensors and proxy sensors without requiring any special handling.