SolarEdge Client (Monitoring API)

A Python client for the SolarEdge Monitoring API (V2), with synchronous and asynchronous interfaces and a method for every documented operation.

Upgrading from 2.x? SolarEdge retired Monitoring API V1 on November 3, 2026, and every request from 2.x now fails with HTTP 410. 3.0 talks to V2, which needs a new API key and has different endpoints and response shapes. See Migrating from 2.x.

Table of Contents

• Features
• Installation
• Credentials
• Quick Start
  • Synchronous Usage
  • Asynchronous Usage
  • Methods
  • Error Handling
• Rate Limits
• Migrating from 2.x
• Development
• API Documentation

Features

• Complete V2 coverage: all 56 operations in SolarEdge's Basic Monitoring (2.1.0) and Advanced Monitoring (2.0.1) APIs, plus get() for anything added later
• Sync & Async Support: MonitoringClient and AsyncMonitoringClient share one definition of every method, so they cannot drift apart
• Typed: full annotations, py.typed, and Literal types for every enumerated parameter
• Safe by default: arguments are validated before anything is sent, and the API key never appears in URLs or error messages

Installation

pip install solaredge
poetry add solaredge
uv add solaredge

Credentials

V1 API keys do not work with V2. Create an account on the SolarEdge Developer Platform and generate an API key there. This client sends it in the X-API-Key header, which every V2 operation accepts.

V2 also supports OAuth 2.0 (Site Access), which lets an app act on behalf of a system owner. That isn't supported here yet. If you need it, please comment on #122.

Quick Start

All time windows take timezone-aware datetimes, which are sent as UTC. V2 rejects timestamps without an offset, so a naive datetime raises SolarEdgeValidationError before any request is sent. Where start/end are optional, leaving them out means "midnight today until now" in the site's time zone.

Synchronous Usage

from datetime import datetime, timedelta, timezone

from solaredge import MonitoringClient

SITE_ID = 1234567
now = datetime.now(timezone.utc)

with MonitoringClient("YOUR_API_KEY") as client:
    details = client.get_site_details(SITE_ID)
    today = client.get_overview(SITE_ID)
    daily = client.get_energy(
        SITE_ID,
        start=now - timedelta(days=30),
        end=now,
        resolution="DAY",
        unit="KWH",
    )
    batteries = client.get_storage_telemetry(SITE_ID)

Asynchronous Usage

import asyncio
from datetime import datetime, timedelta, timezone

from solaredge import AsyncMonitoringClient


async def main():
    now = datetime.now(timezone.utc)
    async with AsyncMonitoringClient("YOUR_API_KEY") as client:
        details, power = await asyncio.gather(
            client.get_site_details(1234567),
            client.get_power(1234567, start=now - timedelta(hours=2), end=now),
        )


asyncio.run(main())

Methods

Every method returns the parsed JSON unchanged. Optional arguments left as None are not sent, so the API's own defaults apply. The API reference lists the paths, parameters and per-resolution window limits.

* Business Pro and Enterprise plans only. Other plans get HTTP 403, raised as SolarEdgeAuthError.

Telemetry, status and lifetime methods cover every device of that kind on the site. Pass serial_numbers=[...] to limit them to specific devices. V2 reports units in upper case ("WH", "KWH", "W"), so compare them case-insensitively.

Error Handling

Every failure raises a SolarEdgeError subclass, so you never need to import httpx to handle one. The originating httpx exception is preserved as __cause__ if you want the transport-level detail.

from solaredge import (
    MonitoringClient,
    SolarEdgeAuthError,
    SolarEdgeRateLimitError,
    SolarEdgeError,
)

with MonitoringClient("YOUR_API_KEY") as client:
    try:
        flow = client.get_current_power_flow(1234567)
    except SolarEdgeAuthError:
        ...  # bad key, or an operation your plan does not include
    except SolarEdgeRateLimitError as exc:
        ...  # exc.retry_after, exc.limits
    except SolarEdgeError:
        ...  # anything else this library raises

The hierarchy:

SolarEdgeAPIError and its subclasses carry status_code, response_body and url.

Rate Limits

Every call costs one credit. Plans set a monthly credit quota and a calls-per-minute limit; the Free tier allows 2,000 credits a month and 10 calls a minute.

This client caps itself at 3 concurrent requests but does not retry or throttle for you. A client that polled several endpoints every 15 minutes under V1 will run through the Free tier's monthly quota. To stay within it:

• Prefer the bulk telemetry methods over per-device ones.
• Use coarser resolutions where you can.
• Poll less often.

Migrating from 2.x

Other changes:

• Credentials: pass a V2 API key; V1 keys are rejected.
• One site per call: V2 has no comma-separated bulk form for sites.
• Datetimes must be timezone-aware, and are sent as UTC from/to.
• Parameters renamed: time_unit is now resolution, and QUARTER_OF_AN_HOUR is now QUARTER_HOUR. Enum values are upper case, e.g. METRIC, PRODUCTION.
• Response bodies differ, so code that reads fields needs updating.
• Data no longer available: optimizer-level telemetry (optimizers appear only in get_devices), and per-phase inverter values (V2 averages across phases).

Development

# Install development dependencies
uv sync
uv run prek install -t commit-msg

# Commiting changes
uv run cz c

API Documentation

• V2 API reference for this library
• SolarEdge Developer Platform documentation
• SolarEdge: Migrating from V1 to V2