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
  • Typed Responses
  • 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, Literal types for every enumerated parameter, and a TypedDict for every response, generated from SolarEdge's specs
• OAuth built in: Site Access tokens are refreshed automatically, with a uv run python -m solaredge login helper for homeowners
• Safe by default: arguments are validated before anything is sent, and credentials never appear in URLs, reprs or error messages

Installation

uv add solaredge

Credentials

V1 API keys do not work with V2. Which V2 credential you need depends on who you are:

SolarEdge only offers Fleet Access keys to installer accounts, so homeowners use OAuth. See SolarEdge's Homeowner and Self-Access Guide.

Homeowners: Site Access (OAuth)

1. Create a developer account: sign in to the Developer Platform with your mySolarEdge login and fill in the developer profile. The Free tier is enough.

2. Create a Site Access application:

   • Service: Monitoring API.
   • Redirect URI: http://localhost:8080/oauth/callback.
   • Scopes: SITE_DATA and DEVICE_DATA.
   • Copy the client secret: it is shown only once.

3. Authorize the app for your site with the bundled helper. It opens the consent page, catches the redirect and saves the token to a file only you can read:

   export SOLAREDGE_CLIENT_SECRET=...   # or omit it to be prompted
   uv run python -m solaredge login --client-id YOUR_CLIENT_ID
   # Saved the token for site 1234567 to solaredge-token.json (mode 600).
   

4. Use the token. Access tokens last 2 hours; OAuth2 refreshes them automatically. Each refresh also replaces the refresh token, so save every new token in on_token_update, or the next run will hold a dead one. A refresh token unused for 14 days expires, and you have to run login again.

import json
from pathlib import Path

from solaredge import MonitoringClient, OAuth2, OAuthToken

TOKEN_FILE = Path("solaredge-token.json")


def save(token: OAuthToken) -> None:
    TOKEN_FILE.write_text(json.dumps(token.to_dict()))


auth = OAuth2(
    OAuthToken.from_dict(json.loads(TOKEN_FILE.read_text())),
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    on_token_update=save,
)

with MonitoringClient(oauth=auth) as client:
    overview = client.get_overview(auth.token.site_id)

OAuth2 works with both clients. With AsyncMonitoringClient, on_token_update may be an async function. Concurrent requests share a single refresh, so they never spend the same refresh token twice.

If you already manage tokens yourself, for example through Home Assistant's OAuth helper, pass the current one with MonitoringClient(access_token="...").

Building an app for other homeowners? solaredge.oauth has the pieces: authorization_url, parse_callback, exchange_code, refresh_token, revoke_token, and their async_ variants.

Installers: Fleet Access (API key)

Create a Fleet Access application on the Developer Platform and pass its key: MonitoringClient("YOUR_API_KEY"). It is sent in the X-API-Key header, and it is the only credential accepted by get_sites and get_alerts, which list data across a fleet.

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.

The examples below use auth, the OAuth2 object from Credentials. With a Fleet Access key, pass api_key="..." instead.

Synchronous Usage

from datetime import datetime, timedelta, timezone

from solaredge import MonitoringClient

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

with MonitoringClient(oauth=auth) 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(oauth=auth) 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, typed as a TypedDict (see Typed Responses). 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.

Typed Responses

Responses are annotated with TypedDicts generated from SolarEdge's OpenAPI specs, so your editor completes field names and a type checker catches a misspelt key. The async client returns awaitables of the same types.

from solaredge.types import Measurements

power: Measurements = client.get_power(SITE_ID)
for sample in power.get("values", []):
    print(sample.get("timestamp"), sample.get("value"))

They are type hints only: at runtime every response is still a plain dict. Fields the spec doesn't mark as required are NotRequired, because real responses can leave them out, so prefer .get() for those. All the types live in solaredge.types.

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 credentials, 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: V1 keys are rejected. Homeowners use Site Access (OAuth); installers use a V2 Fleet Access API key. See Credentials.
• 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

# Committing changes
uv run cz c

# Regenerate solaredge/types.py from the specs in specs/
uv run --group codegen scripts/gen_types.py
# ...or download SolarEdge's latest published specs first
uv run --group codegen scripts/gen_types.py --fetch

Releasing

Releases are automatic. Every merge to main runs the full test suite, then commitizen reads the conventional commits since the last tag:

• fix: releases a patch, feat: a minor version, and BREAKING CHANGE (or feat!:) a major version.
• docs:, ci:, test:, chore: and the like don't release anything.

When there's something to release, CI commits the version bump and CHANGELOG to main, creates the tag and GitHub release, and publishes to PyPI.

• The PR title decides the release. PRs are squash-merged, so the title becomes the commit commitizen reads. Give it the right type, and mark breaking changes with ! (e.g. feat!: ...) or a BREAKING CHANGE: footer in the squash message. A CI check rejects titles that aren't conventional commits. To merge without releasing, use a non-release type like docs: or ci:.
• Don't bump or tag by hand. No local cz bump, no bump PRs, no manual tags or GitHub releases. CI picks the version.
• If a release fails partway, e.g. PyPI was down after the tag was created, use Re-run failed jobs on that run. Re-run all jobs sees the tag already exists and skips publishing.

API Documentation

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