TL;DR
GET /v1/users/{userId}/energy-prices?from=...&to=...&resolution=...— raw EPEX spot prices per time slotstockPriceis in ct/kWh, raw (no grid fees, no taxes, no margin)- Selected day is interpreted in the user's timezone;
timevalues are returned as UTC (...Z) nullstockPriceis legitimate (e.g. day-ahead not yet published) — not an error- Hard cap: 3-day window, bounded by yesterday → tomorrow
- Resolutions:
hourly(default) orquarterHourly - Bidding zone is taken from the user's dynamic tariff if one exists; otherwise it defaults based on the user's timezone (e.g.
Europe/Berlin→DE-LU)
The Energy Prices endpoint returns dynamic electricity stock prices (raw EPEX, before grid fees and taxes) for a user's home, broken down per time slot. It's intended for partner integrations that need short-term spot price exposure — e.g. to display a price curve to the user or align scheduled loads with cheap hours.
This endpoint does not return the user's contractual energy price. For the user's tariff configuration (including grid fees), see Electricity Tariffs.
Endpoint
| Method | Endpoint | Description |
|---|---|---|
GET | /v1/users/{userId}/energy-prices | Raw stock prices per time slot for the user's home |
The home is resolved server-side from the authenticated end-user. The {userId} path segment is required for routing and auditing, but the home is not chosen by the caller.
Authentication
This endpoint uses the same authentication as all Connect API endpoints:
- Scheme: Bearer token (JWT), OAuth2
client_credentials - Scope:
connect_api - User context: The
{userId}path parameter is your external user ID (the same ID you use when provisioning users)
See Authentication for details on obtaining a token.
Request
Query parameters
| Name | Type | Required | Notes |
|---|---|---|---|
from | date (yyyy-MM-dd) | yes | Inclusive start. Must be on or after yesterday. |
to | date (yyyy-MM-dd) | yes | Inclusive end. Must be on or before tomorrow. from <= to. |
resolution | string | no | hourly (default) or quarterHourly. Case-insensitive. |
Maximum window: 3 days (yesterday → tomorrow). This is a hard cap — data outside this window is not available from this endpoint. Partners that need a longer history must collect and store the slots day by day as they are published.
Example request
Code
Response
200 OK
A JSON array of slot objects.
Code
Fields
| Field | Type | Description |
|---|---|---|
time | string | UTC ISO-8601 (...Z). Start of the slot. hourly → top of the hour. quarterHourly → :00, :15, :30, :45. |
stockPrice | decimal? | Raw stock price in ct/kWh, before grid fees, taxes, and margin. null when no price is available for that slot. |
stockPriceis not the price the user pays. It's the EPEX reference price for the user's effective bidding zone. To compute what the user actually pays, add the grid fees from the user's tariff (see Electricity Tariffs) plus the applicable taxes.
Timezone behaviour
The from and to query parameters select a day in the user's timezone. The endpoint internally maps that day to midnight-to-midnight in the user's home timezone and converts to UTC for the underlying lookup.
For example, ?from=2026-06-10&to=2026-06-10 for a user in Europe/Berlin covers 2026-06-09T22:00Z → 2026-06-10T22:00Z during summer (CEST, UTC+2).
Slot timestamps in the response are always UTC (...Z). No localisation is applied server-side — clients should convert to whatever timezone they need to display.
Bidding zone selection
The bidding zone used to source the stock prices is determined as follows:
- From the user's tariff — if the user has an active dynamic tariff with a real bidding zone (e.g.
DE-LU), prices for that zone are returned. - Default by timezone — if the user has no dynamic tariff, or the tariff is on a
flatlinebidding zone (a fixed-rate tariff with no real spot exposure), the bidding zone is defaulted based on the user's timezone (e.g.Europe/Berlin→DE-LU).
Per-slot fallback: when the defaulted zone has no value for a given timestamp, the original value from the user's own zone is returned for that slot (which may be null or 0).
Implication for partners: stockPrice is the EPEX reference price for the user's effective exchange zone — possibly substituted via the defaulting rule above. Do not conflate it with the user's contractual energy price.
Error responses
All errors follow RFC 7807 (application/problem+json).
| Status | Meaning |
|---|---|
400 | Validation failure. errors keyed by from / to / resolution (e.g. missing, out of range, unknown resolution). |
401 | Missing or invalid bearer token. |
403 | Token lacks the connect_api scope. |
404 | The authenticated user has no home. |
429 | Global IP rate limit (100 requests / 10 seconds). |
500 | Unhandled server error. |
Example 400
Code
Important notes
- Units:
stockPriceis in ct/kWh — raw spot price, no fees, no taxes, no margin. - UTC only: Slot timestamps are always UTC. Convert client-side for display.
nullis valid: AnullstockPricemeans no value is available for that slot (e.g. day-ahead not yet published). It is not an error condition.- 3-day cap is hard: Data outside yesterday → tomorrow is not available from this endpoint. Partners that need a longer history must collect and store the slots day by day as they are published.
- No metadata fields: The endpoint deliberately returns only the per-slot list — no current price, no 14-day average, no "has dynamic tariff" flag, no push-enabled flag. Compute what you need from the slot data.
stockPriceis not the user's price: It's the EPEX reference for the user's effective bidding zone — possibly substituted via the bidding zone selection rules. The user's actual price requires adding grid fees and taxes.