Skip to main content

Metrics

Real-time and historical metric retrieval for Sun Sources — latest snapshots, time-series history, aggregations, daily summaries, and fault detection.

Base Route: /api/sunsourcemetrics
Authorization: Omni policy (User, Admin, or Overseer)

Get Latest Metrics​

Returns the most recent telemetry snapshot for a Sun Source.

GET /api/sunsourcemetrics/{sunSourceId}/latest

Response 200 OK​

{
  "sunSourceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "timestamp": "2025-06-20T14:22:00Z",
  "stateOfCharge": 87.5,
  "stateOfHealth": 98.5,
  "batteryVoltage": 52.4,
  "batteryCurrent": 12.3,
  "batteryTemperature": 35.2,
  "solarVoltage": 380.0,
  "solarCurrent": 8.4,
  "solarPower": 3192.0,
  "outputVoltage": 230.0,
  "outputCurrent": 5.2,
  "loadPower": 1196.0,
  "loadPercentage": 45.2,
  "gridVoltage": 230.5,
  "gridFrequency": 50.01,
  "dailyEnergyProduced": 18.5,
  "dailyEnergyConsumed": 12.3,
  "totalEnergyProduced": 4250.0,
  "operatingMode": "Solar",
  "deviceStatus": "Normal",
  "faultCodes": [],
  "warningCodes": []
}

Get Metrics History​

Returns raw time-series metrics within a date range.

GET /api/sunsourcemetrics/{sunSourceId}/history?startTime=2025-06-20T00:00:00Z&endTime=2025-06-20T23:59:59Z&limit=500

Query Parameters​

ParameterTypeDefaultConstraintsDescription
startTimeDateTime24h agoOptionalRange start
endTimeDateTimeNowOptionalRange end
limitint1001–1,000Maximum records returned

Response 200 OK​

Returns an array of SunSourceMetricsDto ordered by timestamp descending.

[
  {
    "sunSourceId": "7c9e6679-...",
    "timestamp": "2025-06-20T14:22:00Z",
    "stateOfCharge": 87.5,
    "solarPower": 3192.0,
    "loadPower": 1196.0,
    ...
  },
  ...
]

Get Aggregated Data​

Returns hourly-aggregated historical data, suitable for charting trends.

GET /api/sunsourcemetrics/{sunSourceId}/aggregated?startTime=2025-06-13&endTime=2025-06-20

Query Parameters​

ParameterTypeDefaultConstraintsDescription
startTimeDateTime7 days agoOptionalRange start
endTimeDateTimeNowOptionalRange end

Maximum range: 90 days. Requests exceeding this are automatically clamped.

Response 200 OK​

[
  {
    "timestamp": "2025-06-20T14:00:00Z",
    "averageBatteryVoltage": 52.1,
    "averageStateOfCharge": 85.0,
    "averageSolarPower": 3100.0,
    "averageLoadPercentage": 42.0,
    "maxSolarPower": 3500.0,
    "minStateOfCharge": 78.0
  }
]

Get Daily Summary​

Returns daily-aggregated summaries including energy totals. Ideal for energy dashboards and reporting.

GET /api/sunsourcemetrics/{sunSourceId}/daily-summary?startTime=2025-06-01&endTime=2025-06-20

Query Parameters​

ParameterTypeDefaultConstraintsDescription
startTimeDateTime7 days agoOptionalRange start
endTimeDateTimeNowOptionalRange end

Maximum range: 400 days.

Response 200 OK​

[
  {
    "date": "2025-06-20",
    "solarPowerAvg": 2100.5,
    "solarPowerMax": 4800.0,
    "loadPowerAvg": 1200.3,
    "loadPowerMax": 3500.0,
    "socAvg": 72.5,
    "socMin": 15.0,
    "socMax": 100.0,
    "voltageAvg": 51.8,
    "gridVoltageAvg": 230.5,
    "gridFreqAvg": 50.01,
    "energyProduced": 21.5,
    "energyConsumed": 14.2,
    "sampleCount": 1440
  }
]

Get Faults​

Returns sources with active fault or warning codes across all of the user's Sun Sources.

GET /api/sunsourcemetrics/faults

Response 200 OK​

Returns an array of SunSourceMetricsDto — only sources that have non-empty faultCodes or warningCodes.

[
  {
    "sunSourceId": "7c9e6679-...",
    "timestamp": "2025-06-20T14:22:00Z",
    "faultCodes": ["F01", "F12"],
    "warningCodes": ["W03"],
    ...
  }
]

Batch Get Latest Metrics​

Returns the latest metrics for multiple Sun Sources in a single request.

POST /api/sunsourcemetrics/batch/latest

Request Body​

[
  "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "550e8400-e29b-41d4-a716-446655440000",
  "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
]

Maximum batch size: 50. IDs are filtered by ownership — only sources belonging to the authenticated user are returned.

Response 200 OK​

{
  "7c9e6679-7425-40de-944b-e07fc1f90ae7": {
    "sunSourceId": "7c9e6679-...",
    "timestamp": "2025-06-20T14:22:00Z",
    "stateOfCharge": 87.5,
    "solarPower": 3192.0,
    ...
  },
  "550e8400-e29b-41d4-a716-446655440000": {
    ...
  }
}

Response Schema: SunSourceMetricsDto​

interface SunSourceMetricsDto {
  sunSourceId: string;
  timestamp: string;                // ISO 8601

  // Battery
  stateOfCharge: number | null;     // Percentage (0-100)
  stateOfHealth: number | null;     // Percentage (0-100)
  batteryVoltage: number | null;    // Volts
  batteryCurrent: number | null;    // Amps
  batteryTemperature: number | null;// °C

  // Solar
  solarVoltage: number | null;     // Volts
  solarCurrent: number | null;     // Amps
  solarPower: number | null;       // Watts

  // Output
  outputVoltage: number | null;    // Volts
  outputCurrent: number | null;    // Amps
  loadPower: number | null;        // Watts
  loadPercentage: number | null;   // Percentage (0-100)

  // Grid
  gridVoltage: number | null;      // Volts
  gridFrequency: number | null;    // Hz

  // Energy
  dailyEnergyProduced: number | null;  // kWh
  dailyEnergyConsumed: number | null;  // kWh
  totalEnergyProduced: number | null;  // kWh (cumulative)

  // Status
  operatingMode: string | null;
  deviceStatus: string | null;
  faultCodes: string[] | null;
  warningCodes: string[] | null;
}

interface SunSourceHistoricalDataDto {
  timestamp: string;
  averageBatteryVoltage: number | null;
  averageStateOfCharge: number | null;
  averageSolarPower: number | null;
  averageLoadPercentage: number | null;
  maxSolarPower: number | null;
  minStateOfCharge: number | null;
}

interface DailySummaryDto {
  date: string;              // "YYYY-MM-DD"
  solarPowerAvg: number;
  solarPowerMax: number;
  loadPowerAvg: number;
  loadPowerMax: number;
  socAvg: number;
  socMin: number;
  socMax: number;
  voltageAvg: number;
  gridVoltageAvg: number;
  gridFreqAvg: number;
  energyProduced: number;    // kWh
  energyConsumed: number;    // kWh
  sampleCount: number;
}