Alerts¶

The Alerts API manages system-generated notifications about rate changes, savings opportunities, billing anomalies, and other actionable events. All endpoints require authentication and are prefixed with /alerts.

GET /alerts¶

List alerts for the authenticated user. Alerts are returned in reverse chronological order (newest first).


Auth required	Yes

Query Parameters¶

Parameter	Type	Default	Description
`is_read`	boolean	-	Filter by read status (`true` or `false`)
`limit`	integer	`50`	Maximum number of alerts to return (max 200)

Example Request¶

curl "https://app.meterbase.io/api/v1/alerts?is_read=false&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

[
  {
    "id": "alert_001",
    "type": "rate_change",
    "severity": "high",
    "title": "Rate increase effective April 1",
    "message": "SCE TOU-GS-2 energy rates are increasing by 8.3%. Your estimated monthly cost for Sunset Apartments will increase by $270.",
    "property_id": "prop_abc123",
    "property_name": "Sunset Apartments",
    "is_read": false,
    "is_dismissed": false,
    "created_at": "2026-03-24T09:00:00Z",
    "metadata": {
      "tariff_id": "trf_sce_tou_gs2",
      "increase_percent": 8.3,
      "effective_date": "2026-04-01"
    }
  },
  {
    "id": "alert_002",
    "type": "savings_opportunity",
    "severity": "medium",
    "title": "Potential savings of $3,600/year",
    "message": "Harbor View Plaza could save $3,600/year by switching from SCE TOU-GS-2 to SCE TOU-GS-3.",
    "property_id": "prop_002",
    "property_name": "Harbor View Plaza",
    "is_read": false,
    "is_dismissed": false,
    "created_at": "2026-03-23T14:00:00Z",
    "metadata": {
      "current_tariff": "SCE TOU-GS-2",
      "recommended_tariff": "SCE TOU-GS-3",
      "annual_savings": 3600.00
    }
  },
  {
    "id": "alert_003",
    "type": "usage_anomaly",
    "severity": "low",
    "title": "Unusual usage detected",
    "message": "Oakwood Residences usage in February was 18% above the rolling average.",
    "property_id": "prop_005",
    "property_name": "Oakwood Residences",
    "is_read": false,
    "is_dismissed": false,
    "created_at": "2026-03-20T11:30:00Z",
    "metadata": {
      "expected_kwh": 12500,
      "actual_kwh": 14750,
      "deviation_percent": 18.0
    }
  }
]

Alert Types

The type field can be one of: rate_change, savings_opportunity, usage_anomaly, bill_due, tariff_expiring, import_complete.

PATCH /alerts/{id}/read¶

Mark an alert as read.


Auth required	Yes

Path Parameters¶

Parameter	Type	Description
`id`	string	Alert ID

Example Request¶

curl -X PATCH https://app.meterbase.io/api/v1/alerts/alert_001/read \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "id": "alert_001",
  "is_read": true,
  "read_at": "2026-03-25T15:00:00Z"
}

Error Cases¶

Status	Detail	Cause
`404`	`"Alert not found"`	Invalid or inaccessible alert ID

PATCH /alerts/{id}/dismiss¶

Dismiss an alert. Dismissed alerts are hidden from the default list view but remain in the system.


Auth required	Yes

Path Parameters¶

Parameter	Type	Description
`id`	string	Alert ID

Example Request¶

curl -X PATCH https://app.meterbase.io/api/v1/alerts/alert_002/dismiss \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "id": "alert_002",
  "is_dismissed": true,
  "dismissed_at": "2026-03-25T15:05:00Z"
}

Error Cases¶

Status	Detail	Cause
`404`	`"Alert not found"`	Invalid or inaccessible alert ID