Get Sensor History

Overview

This endpoint queries InfluxDB for recent sensor readings and evaluates the latest data point for state transitions. It serves as the Single Source of Truth for time-series data in the system.

Key Features

Time-Range Queries: Retrieve sensor data within a configurable time window (10-3600 seconds)
Event Detection: Automatically evaluates latest reading for anomaly transitions
Chronological Ordering: Returns data sorted oldest-first for correct chart rendering
Feature Enrichment: Includes batch statistical features when available

Path Parameters

asset_id

string

required

Unique identifier for the asset (e.g., Motor-01, Pump-A3)

Query Parameters

limit

integer

default:"100"

Maximum number of data points to return. Range: 1-1000.Use lower values for real-time dashboards, higher values for historical analysis.

range_seconds

integer

default:"60"

Time range in seconds to query backwards from now. Range: 10-3600.Examples:

60 = Last 1 minute
300 = Last 5 minutes
3600 = Last 1 hour

Response

asset_id

string

The asset identifier from the request

sensor_data

array

Array of sensor readings sorted chronologically (oldest first).Each reading contains:

Show Sensor Reading Object

timestamp

string

ISO 8601 timestamp of the reading

voltage_v

float

Voltage reading in Volts

current_a

float

Current reading in Amperes

power_factor

float

Power factor (0.0-1.0)

vibration_g

float

Vibration intensity in g-force

is_faulty

boolean

Whether this reading was flagged as anomalous.Set to true when sensor values deviate from baseline by >25% tolerance.

_batch_features

object

Batch statistical features computed over the last N readings (Phase 5).Only present on the most recent reading when monitoring loops are active.

{
  "voltage_v_std": 2.3,
  "voltage_v_peak_to_peak": 8.5,
  "current_a_std": 1.1,
  "current_a_peak_to_peak": 4.2,
  "power_factor_std": 0.012,
  "vibration_g_std": 0.023,
  "vibration_g_peak_to_peak": 0.09
}

events

array

Array of state transition events detected from the latest reading.Events are emitted ONLY on transitions (healthy→faulty or faulty→healthy), never for sustained states.

Show Event Object

timestamp

string

ISO 8601 timestamp of the event

type

string

Event type:

ANOMALY_DETECTED - Transition from healthy to faulty
ANOMALY_CLEARED - Transition from faulty to healthy
DEGRADATION_WARNING - Degradation index crossed threshold
HEARTBEAT - Periodic health check (reserved)

severity

string

Event severity:

info - Normal operational events (ANOMALY_CLEARED)
warning - Early degradation warnings (15%, 30% thresholds)
critical - Urgent attention required (ANOMALY_DETECTED, 50%+ thresholds)

message

string

Plain-English diagnostic explanation of the event.Examples:

"ANOMALY: Vibration spike (0.45g) — possible bearing wear; Power factor degradation (0.82)."
"RECOVERY: All sensor readings have returned to within normal operating range."
"Motor fatigue reached 30% (DI=0.3012). Remaining Useful Life: 240.5h."

count

integer

Number of sensor readings returned (length of sensor_data array)

Example Request

curl -X GET "http://localhost:8000/api/v1/data/history/Motor-01?limit=50&range_seconds=300"

Example Response

Normal Operation (No Events)

{
  "asset_id": "Motor-01",
  "sensor_data": [
    {
      "timestamp": "2026-03-02T14:25:00.000000Z",
      "voltage_v": 230.2,
      "current_a": 15.1,
      "power_factor": 0.95,
      "vibration_g": 0.02,
      "is_faulty": false
    },
    {
      "timestamp": "2026-03-02T14:25:01.000000Z",
      "voltage_v": 230.5,
      "current_a": 15.3,
      "power_factor": 0.94,
      "vibration_g": 0.02,
      "is_faulty": false
    },
    {
      "timestamp": "2026-03-02T14:25:02.000000Z",
      "voltage_v": 230.1,
      "current_a": 15.0,
      "power_factor": 0.95,
      "vibration_g": 0.03,
      "is_faulty": false,
      "_batch_features": {
        "voltage_v_std": 2.1,
        "voltage_v_peak_to_peak": 7.8,
        "current_a_std": 1.0,
        "current_a_peak_to_peak": 3.9,
        "power_factor_std": 0.009,
        "vibration_g_std": 0.018,
        "vibration_g_peak_to_peak": 0.08
      }
    }
  ],
  "events": [],
  "count": 3
}

Anomaly Detection Event

{
  "asset_id": "Motor-01",
  "sensor_data": [
    {
      "timestamp": "2026-03-02T15:42:30.000000Z",
      "voltage_v": 245.2,
      "current_a": 22.5,
      "power_factor": 0.78,
      "vibration_g": 0.52,
      "is_faulty": true,
      "_batch_features": {
        "voltage_v_std": 8.3,
        "voltage_v_peak_to_peak": 28.5,
        "current_a_std": 4.2,
        "current_a_peak_to_peak": 15.1,
        "power_factor_std": 0.045,
        "vibration_g_std": 0.089,
        "vibration_g_peak_to_peak": 0.31
      }
    }
  ],
  "events": [
    {
      "timestamp": "2026-03-02T15:42:30.000000Z",
      "type": "ANOMALY_DETECTED",
      "severity": "critical",
      "message": "ANOMALY: High vibration variance (mechanical jitter): σ=0.0890g; Vibration transient spike: peak-to-peak=0.310g; High voltage variance (grid instability): σ=8.30V."
    }
  ],
  "count": 1
}

Recovery Event

{
  "asset_id": "Motor-01",
  "sensor_data": [
    {
      "timestamp": "2026-03-02T15:50:15.000000Z",
      "voltage_v": 230.3,
      "current_a": 15.2,
      "power_factor": 0.94,
      "vibration_g": 0.02,
      "is_faulty": false
    }
  ],
  "events": [
    {
      "timestamp": "2026-03-02T15:50:15.000000Z",
      "type": "ANOMALY_CLEARED",
      "severity": "info",
      "message": "RECOVERY: All sensor readings have returned to within normal operating range."
    }
  ],
  "count": 1
}

Event Engine Behavior

Core Architectural Rule: Events are transitions, NOT states.The Event Engine maintains per-asset state tracking and emits events ONLY when is_faulty changes:

healthy → faulty → Emits ANOMALY_DETECTED (critical)
faulty → healthy → Emits ANOMALY_CLEARED (info)
same state → No event emitted

Debouncing: Requires 2 consecutive matching evaluations before confirming a transition to prevent false positives from transient noise.

Data Persistence

This endpoint queries InfluxDB directly as the Single Source of Truth for time-series data.In-memory _sensor_history is used only for:

Feature enrichment (_batch_features)
Fast recent-data access in monitoring loops

All persistent queries should use this endpoint, not in-memory storage.

Integration Workflow

Use Cases

Real-Time Dashboard Charts

// Poll every 1 second for last 60 seconds of data
setInterval(async () => {
  const response = await fetch(
    '/api/v1/data/history/Motor-01?range_seconds=60&limit=60'
  );
  const {sensor_data, events} = await response.json();
  
  updateChart(sensor_data);
  
  if (events.length > 0) {
    showAlert(events[0]);
  }
}, 1000);

Historical Analysis

# Get last hour of data for analysis
curl -X GET "http://localhost:8000/api/v1/data/history/Motor-01?limit=1000&range_seconds=3600" \
  | jq '.sensor_data[] | select(.is_faulty == true)'

Health Status - Get aggregated health metrics derived from this data
Events - Dedicated events documentation
Simple Ingest - Write sensor data that this endpoint reads

Getting Started

Ingestion

System Control

Integration

Operator

Reporting

Sandbox

Overview

Key Features

Path Parameters

Query Parameters

Response

Example Request

Example Response

Normal Operation (No Events)

Anomaly Detection Event

Recovery Event

Event Engine Behavior

Data Persistence

Integration Workflow

Use Cases

Real-Time Dashboard Charts

Historical Analysis

Build docs developers (and LLMs) love

Getting Started

Ingestion

System Control

Integration

Operator

Reporting

Sandbox

​Overview

​Key Features

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

​Normal Operation (No Events)

​Anomaly Detection Event

​Recovery Event

​Event Engine Behavior

​Data Persistence

​Integration Workflow

​Use Cases

​Real-Time Dashboard Charts

​Historical Analysis

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Key Features

Path Parameters

Query Parameters

Response

Example Request

Example Response

Normal Operation (No Events)

Anomaly Detection Event

Recovery Event

Event Engine Behavior

Data Persistence

Integration Workflow

Use Cases

Real-Time Dashboard Charts

Historical Analysis

Related Endpoints