Meters Endpoint

Meters track utility consumption for a building. Each meter belongs to a building and has a type (electricity, gas, water, etc.). Readings are submitted against a meter.

Base path: /v1/buildings/{building_id}/meters

List meters

curl https://api.sdx.dev/v1/buildings/bld_3nf7p2q1/meters \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "mtr_e1f2g3h4",
      "building_id": "bld_3nf7p2q1",
      "type": "electricity",
      "name": "Main Grid Supply",
      "unit": "kWh",
      "source": "automated_feed",
      "provider": "Pacific Gas & Electric",
      "status": "active",
      "latest_reading_date": "2026-01-31",
      "created_at": "2025-06-15T09:15:00Z"
    },
    {
      "id": "mtr_i5j6k7l8",
      "building_id": "bld_3nf7p2q1",
      "type": "natural_gas",
      "name": "Gas Main",
      "unit": "therms",
      "source": "manual",
      "provider": null,
      "status": "active",
      "latest_reading_date": "2025-12-31",
      "created_at": "2025-06-15T09:16:00Z"
    }
  ],
  "meta": { "total": 2, "page": 1, "per_page": 50, "total_pages": 1 }
}

Create a meter

curl -X POST https://api.sdx.dev/v1/buildings/bld_3nf7p2q1/meters \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "water",
    "name": "Potable Water Main",
    "unit": "litres"
  }'

Required fields: type, unit

Supported meter types: electricity, natural_gas, water, district_heating, district_cooling, steam, fuel_oil, diesel, lpg, solar, chp, waste_landfill, waste_recycling, waste_compost

Submit a reading

curl -X POST https://api.sdx.dev/v1/buildings/bld_3nf7p2q1/meters/mtr_e1f2g3h4/readings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-02-01",
    "end_date": "2026-02-28",
    "consumption": 38200,
    "cost": 4750.00,
    "cost_currency": "USD",
    "demand_kw": 172
  }'

Response (201 Created):

{
  "data": {
    "id": "rdg_q3r4s5t6",
    "meter_id": "mtr_e1f2g3h4",
    "start_date": "2026-02-01",
    "end_date": "2026-02-28",
    "consumption": 38200,
    "unit": "kWh",
    "cost": 4750.00,
    "cost_currency": "USD",
    "demand_kw": 172,
    "source": "api",
    "anomaly_flags": [],
    "created_at": "2026-03-01T10:00:00Z"
  }
}

Required fields: start_date, end_date, consumption

Submit readings in batch

Submit multiple readings for one meter in a single request (up to 500 readings per batch):

curl -X POST https://api.sdx.dev/v1/buildings/bld_3nf7p2q1/meters/mtr_e1f2g3h4/readings/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "readings": [
      { "start_date": "2025-01-01", "end_date": "2025-01-31", "consumption": 41000 },
      { "start_date": "2025-02-01", "end_date": "2025-02-28", "consumption": 37500 },
      { "start_date": "2025-03-01", "end_date": "2025-03-31", "consumption": 39800 }
    ]
  }'

Response (201 Created):

{
  "data": {
    "accepted": 3,
    "rejected": 0,
    "readings": [ ... ]
  }
}

If some readings fail validation, the response includes both accepted and rejected counts with error details for each rejected reading.

List readings

curl "https://api.sdx.dev/v1/buildings/bld_3nf7p2q1/meters/mtr_e1f2g3h4/readings?start_date=2025-01-01&end_date=2025-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters:

Delete a reading

curl -X DELETE https://api.sdx.dev/v1/buildings/bld_3nf7p2q1/meters/mtr_e1f2g3h4/readings/rdg_q3r4s5t6 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: 204 No Content

Locked readings cannot be deleted. Attempting to do so returns 403 with error code building_locked.

Anomaly detection

SDX automatically flags readings that appear anomalous. Flags are included in the reading response:

Required scopes

Next steps

• Benchmarks endpoint
• Buildings endpoint
• Submitting data guide