Metrics

Numeric telemetry — every point a device sends with px.send(name, value). Three endpoints: discover what's been reported, get the latest values, and query a time-range with auto-downsampling.

List metric names

Returns the distinct metric names a device has ever reported. Useful for populating a picker or sanity-checking the device's surface area.

Example

curl https://api.plexus.company/v1/sources/robot-01/metrics \
  -H "x-api-key: YOUR_API_KEY"

Response

["battery.percent", "cpu.percent", "motor.rpm"]

Latest values

The most recent value for every metric on a device. Source is ClickHouse, so this is eventually-consistent within a few seconds — not a live feed. The lookback is one hour: metrics that haven't been reported in the last hour drop out of the response.

Example

curl https://api.plexus.company/v1/sources/robot-01/metrics/latest \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "metrics": {
    "battery.percent": 87.0,
    "cpu.percent": 14.2,
    "motor.rpm": 3200.0
  }
}

Historical query

Time-series for one or more metrics with automatic downsampling. Windows under ~10 minutes return raw points; longer windows return pre-aggregated buckets (1m, 10m, 1h, or 1d).

Query params

Example

curl "https://api.plexus.company/v1/sources/robot-01/metrics/query?metrics=battery.percent&last=1h" \
  -H "x-api-key: YOUR_API_KEY"

Response — raw

Returned for windows under ~10 minutes. Each metric carries parallel timestamp_ms + value arrays, capped at 10 000 rows.

{
  "interval": "raw",
  "auto_downsampled": false,
  "series": {
    "battery.percent": {
      "timestamp_ms": [1746969600000, 1746969660000],
      "value": [87.0, 86.5]
    }
  },
  "truncated": false
}

Response — downsampled

Longer windows return min/max/avg/count arrays instead of value. Plexus picks an interval (1m, 10m, 1h, or 1d) that returns roughly a thousand points. truncated is true when any result — raw or aggregated — hit the 10 000-row cap. Forcing a coarser interval reduces rows but can still truncate; narrow the window if it does.

{
  "interval": "1h",
  "auto_downsampled": true,
  "series": {
    "battery.percent": {
      "timestamp_ms": [1746969600000, 1746973200000],
      "min": [82.0, 79.0],
      "max": [91.0, 88.0],
      "avg": [86.5, 83.1],
      "count": [360, 360]
    }
  },
  "truncated": false
}

Live data

For real-time metric streaming, connect to the data API's WebSocket endpoint:

wss://api.plexus.company/v1/sources/{source_id}/metrics/stream

Send {"type": "auth", "api_key": "plx_..."} as the first frame, then receive telemetry frames as they arrive. See Live streams for the full protocol, query params, and frame shapes.

Polling /metrics/latest on an interval (3–10s is typical) remains a fine option when you'd rather not hold a socket open.