Timeseries API

Overview

The Timeseries API exposes bounded meter telemetry queries for external integrations. The current public surface supports electricity meters.

Base path: /api/v1/timeseries/electricity

Authentication

All endpoints require authentication. Include a valid Bearer token in the Authorization header: Authorization: Bearer <access_token>.

Account scoping

Every request must include account_id. Requested meter serial numbers must belong to that account.

Common query parameters

• account_id (uuid, required)
• meter_sn (string, required)
• start (ISO 8601 datetime, required)
• end (ISO 8601 datetime, required)
• bucket_minutes (integer, optional, default 30, max 1440)

Endpoints

Energy profile

GET /api/v1/timeseries/electricity/energy-profile

Returns interval energy/profile buckets for one meter.

Power profile

GET /api/v1/timeseries/electricity/power-profile

Returns interval power buckets for one meter.

Latest power

GET /api/v1/timeseries/electricity/latest-power

Returns the latest power point inside the requested time range.

Energy sum

GET /api/v1/timeseries/electricity/energy-sum

Returns summed import, export, and kVA values for one meter over the requested time range.

Batch energy sums

POST /api/v1/timeseries/electricity/energy-sums

Body:

{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "meter_sns": ["METER-001", "METER-002"],
  "start": "2026-05-01T00:00:00.000Z",
  "end": "2026-05-08T00:00:00.000Z",
  "bucket_minutes": 30,
  "max_meters_per_query": 100
}

Returns one summed result per requested meter serial number. The API chunks large meter lists internally to avoid oversized telemetry queries.