API basics

The three things you’ll do most with the Plexus Data API: discover what’s in your fleet, pull historical data, and subscribe to live updates. All examples use curl — get your key from API Keys.

Step 1 — List your devices


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


{
  "devices": [
    { "source_id": "robot-01", "online": true,  "last_seen_ms": 1746969600000 },
    { "source_id": "robot-02", "online": false, "last_seen_ms": 1746883200000 }
  ]
}

Filter to online devices only with ?status=online. last_seen_ms is Unix milliseconds.

Step 2 — Discover what a device reports


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


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

Returns the distinct metric names the device has ever reported. Useful before building queries or dashboards so you know what’s available.

Step 3 — Fetch the latest values


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


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

Eventually consistent within a few seconds — not a live feed. For real-time values, use the WebSocket stream in Step 5.

Step 4 — Query historical data


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


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

Windows under ~10 minutes return raw points with a value array. Longer windows auto-downsample — Plexus picks an interval (1m, 10m, 1h, or 1d) that returns roughly a thousand points, and replaces value with min/max/avg/count arrays:


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


{
  "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]
    }
  }
}

Force a specific interval with ?interval=10m, or pass interval=raw to opt out of downsampling (capped at 10 000 rows — narrow the window if truncated comes back true).

Query multiple metrics and an absolute range with start/end:


curl "https://api.plexus.company/v1/sources/robot-01/metrics/query?metrics=cpu.percent,battery.percent&start=2026-05-01T00:00:00Z&end=2026-05-02T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"

See Metrics for the full query parameter reference.

Step 5 — Stream live data

For real-time values, open a WebSocket and send an auth frame:


const ws = new WebSocket(
  "wss://api.plexus.company/v1/sources/robot-01/metrics/stream?metrics=battery.percent,cpu.percent"
);
 
ws.onopen = () => {
  ws.send(JSON.stringify({ type: "auth", api_key: "plx_..." }));
};
 
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === "telemetry") {
    for (const pt of msg.points) {
      console.log(pt.metric, pt.value, pt.timestamp);
    }
  }
};
 
ws.onclose = ({ code, reason }) => {
  console.warn("closed", code, reason);
  // reconnect after a short delay
};

The auth frame must be the first frame you send — the socket closes with 4401 if it doesn’t arrive within 10 seconds. Omit metrics from the query string to receive all metrics for the device.

See Live streams for the full frame reference and close codes.