The European Energy Data API

A single interface for European fundamentals

The Voltstack Data API exposes the same European energy fundamentals that power the Voltstack Analytics terminal. Every endpoint returns JSON over HTTPS, designed for two patterns: low-latency polling for live desks, and scheduled pulls for analytics pipelines. The API is read-only and spans four domains:

• Power — day-ahead prices across 11 bidding zones, cross-border physical flows, actual generation by fuel across 9 countries, a real merit-order supply stack, and RTE's French wind and solar generation forecasts and its purchase-obligation aggregate.
• Gas — country/aggregate storage, LNG send-out and inventory, physical pipeline flows at major import points, GB system physicals, and Norwegian gas system events (Gassco REMIT urgent market messages: field and terminal unavailability, events rather than flows).
• History — settled day-ahead price history, derived realized volatility, gas-storage history with a real five-year band, LNG send-out history, and commodity benchmarks (Brent, WTI, Henry Hub, EU gas, coal).
• Carbon — EEX EUA primary-auction results, licensed and served at /v1/carbon/eua-auctions; EUA/UKA spot and forward pricing stays ENTERPRISE
• Weather — temperature, wind and precipitation forecasts with heating/cooling degree days.

All endpoints sit under one versioned base path. The major version is pinned in the path; additive changes (new fields, new zones) ship without a version bump.

Base URL   https://api.voltstack.energy/v1
Protocol   HTTPS only (TLS 1.2+)
Format     application/json; charset=utf-8
Methods    GET (read-only)

The /v1 surface is read-only and has two access tiers, set for the surface as a whole rather than per path. As measured on 22 September 2026: a request carrying a valid data API key is answered at full depth on every documented path, and a request carrying no key is answered as a labelled sample. Since 24 September 2026 five of those paths are paused and answer neither way (Paused endpoints, below). A sample response is the same envelope with a sample block added (§04). Current-data endpoints serve their standard recent window. History endpoints serve at most the most recent 30 days: a window that starts earlier is narrowed to that floor and still labelled, a window that ends at or before the floor is refused with 401 api-key-required, and the CSV export refuses an anonymous request whose from and to are not both ISO days inside the window, because a narrowed file could not carry the label. Anonymous requests also carry a per-address rate limit (§07). An endpoint that additionally requires a signed-in tenant (§06) still refuses a caller who is not one. The tiers are deployment configuration and can change without a new revision of this document, which is why the statement is dated. A keyed request is never narrowed, never labelled and does not depend on that configuration, so build every integration keyed. Ask data@voltstack.energy before you rely on the sample tier for anything.

A data API key is a token of the form vsk_live_<key_id>_<secret> — a ten-character public lookup handle and a forty-character secret, both base62. It is presented in the X-API-Key header; an Authorization: Bearer header carrying the same token is also accepted. Keys are issued on request at research@voltstack.energy. Server-side each key is a row carrying its own identity, so keys are issued, listed, rotated and deactivated individually and usage is attributed per key. For those keys only the SHA-256 digest of the secret is held at rest, and comparison is constant-time, so a key cannot be recovered from the key store and cannot be guessed by timing. A configured DATA_API_KEYS list on the web service is also honoured, as a break-glass path that verifies without the key store. An entry on that list is either the SHA-256 digest of a token or, in the older form, the token itself. The older form is a plaintext credential held in the hosting provider's service configuration, not a digest, and as at this revision at least one issued key is still held that way. Keys on the list carry no per-key usage record.

Every issued key also carries one or more scopes, fixed when the key is issued: history covers the settled-history endpoints under /v1/history, current covers every other documented path (live power, gas, weather and benchmark feeds), and all covers both. A valid key presented on an endpoint outside its scopes is refused with 403 and error: "insufficient-scope". This is a different refusal from the 401 above: the credential itself verified, the grant is what falls short, so re-presenting the same key cannot succeed. The refusal names the scope the endpoint requires and the scopes the key was granted; it never echoes the key. Keys honoured through the break-glass DATA_API_KEYS list carry no scope restriction. To extend an issued key's scopes, write to research@voltstack.energy.

Paused endpoints. As at 24 September 2026, five documented paths are paused while Voltstack confirms redistribution rights with their publishers: /v1/power/imbalance-de, /v1/power/grid-stress and /v1/power/balancing-stress (netztransparenz.de), /v1/power/constraints (JAO) and /v1/history/n2ex-dayahead (Nord Pool N2EX). Each answers every request with 451 and the body shown below, whatever it carries and before any credential is checked, so neither a retry nor another key changes the answer. /v1/power/imbalance keeps answering, but its four German control-area rows come from netztransparenz.de and are withheld: the ENTSO-E areas are served as before, and each German area reads paused in meta.areaStatus. Bulk extracts of the same datasets are paused as well. A later revision of this document records each publisher's answer and the date its endpoints return.

# Keyed request
curl "https://api.voltstack.energy/v1/history/day-ahead?zone=DE_LU&from=2026-01-01&to=2026-07-01" \
  -H "X-API-Key: vsk_live_<key_id>_<secret>"

# No key: 200, the same envelope with a sample block added:
curl "https://api.voltstack.energy/v1/power/day-ahead"
  "sample": { "sample": true, "window": "recent", "detail": "Anonymous sample tier. Full depth requires a data API key ..." }

# No key, a history window ending at or before the 30-day floor: 401
{ "error": "api-key-required",
  "detail": "Anonymous access is limited to a 30-day sample window. Full-depth history requires a data API key in the X-API-Key header. Request one at research@voltstack.energy." }

# An invalid, revoked or expired key returns 401 on every path, before any parameter is read:
{ "error": "api-key-required", "reason": "invalid-key",
  "detail": "This endpoint requires a data API key in the X-API-Key header. Request one at research@voltstack.energy." }

# A valid key presented outside its scopes returns 403:
{ "error": "insufficient-scope",
  "detail": "This API key does not carry the 'history' scope required by this endpoint (granted: current). To extend the key's scopes, contact research@voltstack.energy." }

# Any request to a paused endpoint returns 451:
{ "error": "unavailable",
  "reason": "This dataset is paused while we confirm redistribution rights with its publisher." }

Every response is wrapped in a uniform envelope — the core of Voltstack's data-integrity model. Each payload declares whether the value is live upstream data or a transparent fallback, when it was sourced, and whether it was cached. Consumers never receive a silently stale or fabricated value.

{
  "source":   "entsoe",            // canonical upstream identifier
  "live":     true,                // true = real upstream; false = treat as fallback
  "data":     { /* domain payload */ },
  "fetchedAt": 1781622120092,       // epoch ms the value was obtained
  "cached":   false,               // served from the server-side TTL cache
  "reason":   null,                // when live=false: "no-token" | "upstream-error" | "rate-limited" | "disabled"
  "meta": {                        // per-payload provenance
    "upstream": "ENTSO-E Transparency (A44)",
    "unit": "EUR/MWh (zone currency)", "timezone": "UTC",
    "completeness": 0.998,          // [0,1] fraction of expected points arrived (history)
    "gaps": [],                      // timestamp ranges with missing data (history)
    "dataAgeSeconds": 642,           // seconds since the rows were last written
    "dataAsOf": 1781650800000      // epoch ms of the newest data point
  }
}

The dislocation surface: physical constraint and event data behind the price series. Field-level detail for every payload is in the Data Dictionary §14–25. None of these endpoints carries a simulated fallback — when an upstream has nothing, the envelope says so.

{ "eventCount":1, "activeNowCount":1, "asOfMs":1789387200000,
  "activeNowUnavailable":[ { "unit":"mcm/d", "unavailable":18.2, "events":1 } ],
  "events":[ { "messageId":"2026-304__________________003", "eventStatus":"Active", "unavailabilityType":"Planned",
    "eventType":"Other unavailability", "unavailabilityReason":"Yearly maintenance", "assets":["Troll"],
    "capacity":{ "unit":"mcm/d", "unavailable":18.2, "available":114.0, "technical":132.2 },
    "eventStartMs":1789185600000, "eventStopMs":1789617600000, "publishedAtMs":1789184009020,
    "balancingZones":["21Y000000000024I", "21Y0000000001278", "21YGB-UKGASGRIDW", "21YNL----TTF---1", "37Y701125MH0000I", "37Y701133MH0000P"],
    "participant":"Gassco AS", "participantEic":"21X-NO-A-A0A0A-2" } ] }

Server-side caching is matched to each upstream's true publication cadence — polling faster than the TTL simply returns the cached value with cached:true.

Voltstack applies two rate limits of its own, each counted per endpoint over a one-minute window. A keyed request counts against its key: 120 requests a minute by default, with per-key overrides on request. A request carrying no key counts against its client address, an IPv6 address by its /64: 60 requests a minute. Past either limit the response is 429 with a Retry-After header in seconds, X-RateLimit-Limit and X-RateLimit-Remaining, and a body of error: "rate-limited" with retryAfterSeconds. The counters live in the memory of a single web instance and restart with it. Separately from both, the server-side TTL cache above means polling faster than the TTL only returns cached values, and upstream back-off is a different signal: it surfaces as 200 with live:false and reason:"rate-limited", not as a 429. Fair use applies during early access.

A transport error is a non-2xx status; a data fallback is 200 with live:false. A request for a feed whose upstream is briefly unavailable still returns 200 with a reason, so pipelines degrade gracefully rather than break.

v1.21 · 2026-10-25: /v1/power/fr-generation-forecast serves RTE's purchase-obligation aggregate one RTE run at a time. Its horizon names the run after a slash (D-1/DA02, ID/ID07), as RTE's sub_type does; before, several runs were stored under one horizon and the last one RTE listed kept for each interval. Aggregate rows stored before this revision are no longer served, here or as recorded revisions; §07, §09 and the point-in-time note say so. Wind and solar are unchanged, and no other endpoint, field or status code changed. v1.20 · 2026-10-25: /v1/carbon/eua-auctions now names its attribution as Source: EEX, the line the platform shows beside the same data; Source: EEX Group belongs to the EEX DataSource data a desk brings itself. §01 and §09 name RTE's purchase-obligation aggregate rather than an aggregate, as the /v1/power/fr-generation-forecast entry already did. No endpoint, field or status code changed. v1.19 · 2026-10-23: §06 gains /v1/power/fr-generation-forecast, RTE's French generation forecast, and /v1/carbon/eua-auctions, EEX's EUA primary auction results, each served from the store the terminal already reads, with a row each in §07. §01 and §09 no longer say their /v1 paths follow. No other endpoint, field or status code changed. v1.18 · 2026-10-01: Publisher details: Voltstack Limited, Dublin, Ireland. No endpoint, field or status code changed. v1.17 · 2026-09-28: the point-in-time capture note no longer says German redispatch measures and GB balancing acceptances are version-captured with a publication timestamp since 2026-07-14, since neither source gives one. It points each at the date /coverage shows for it, says what version 1 of each carries as published_at (the measure's own window start, or Elexon's own acceptance time), and says which fields of a GB acceptance make a version and that its matched price and side are corrected in place. REMIT UMMs and unit outages are unchanged. §06's /v1/power/gb-balancing entry now describes its figures as they are computed: the top-of-stack accepted offer and bid prices and the top-of-stack offer's spread over MID (it read "accepted offer/bid spread vs MID"), none of them an average, so the acceptance weighting does not apply to them and a segment counted twice never moved them. It says what changed for them from the date /coverage shows for GB balancing acceptances, in each day's last periods: those no longer take in the day before's segments that ran past midnight and now include the day's own segments that ran past midnight and were accepted after its last pass, so topOfStackOffer, topOfStackBid and bmMidSpread can differ there, and a repair may restate the values stored before that date. It gives the numbers of a day's last periods on the 46- and 50-period days, and says that the day before's segments had gone into periods 45 and 46 on the day after the March change and 47 and 48 on the October change day, which can differ there too. It says that a segment accepted after the day's last pass that ends by midnight is still not read. It points to the CSV export for the energy-weighted accepted prices, which change from that date as Methodology Guide §04 describes. No endpoint, field or status code changed. v1.16 · 2026-09-24: §06's /v1/power/imbalance entry says what the endpoint answers when ENTSO-E returns no price for any of its five areas. Nothing is then left to serve, so the answer is live false with reason upstream-error and data null, and any German rows it withheld still read paused in meta.areaStatus. It could previously come back live with an empty areas map. No endpoint, field or status code changed. v1.15 · 2026-09-24: /v1/gas/norway-events no longer says the Gassco nominations are not ingested. Gassco confirmed on 15 September that they are covered and Voltstack now stores them for the workspace, but they appear in no payload on this surface, and Norwegian pipeline flows are still not ingested. No endpoint, field or error changed. v1.14 · 2026-09-24: five endpoints are paused while Voltstack confirms redistribution rights with their publishers, on a founder ruling of this date: /v1/power/imbalance-de, /v1/power/grid-stress and /v1/power/balancing-stress (netztransparenz.de), /v1/power/constraints (JAO) and /v1/history/n2ex-dayahead (Nord Pool N2EX). Each answers every request, keyed or not, with 451 and error "unavailable". §03 states the pause and its date, §06 marks the five PAUSED, and §08 gains the 451 row while its 401 row now excludes paused endpoints. /v1/power/imbalance keeps its ENTSO-E areas and withholds the four German rows, which read paused in meta.areaStatus, a value §04 now lists. §09 splits GB gas physicals from the N2EX auction history and marks the netztransparenz and JAO rows paused. The cover ticker no longer prints a GB N2EX price. v1.13 · 2026-09-23: §06 documents as_of on the four captured settled-history endpoints (day-ahead, n2ex-dayahead, gas-storage with its area, lng-terminals): the window as captured at an instant, read from the vintage sidecar and never from the latest values, with data.pointInTime; the refusal for an instant before capture; the 200 live:false answer, with reason as-of-nothing-captured or as-of-only-implausible, for a window with nothing to serve; what meta.dataAsOf and meta.dataAgeSeconds describe on that read; that an answer is final once as_of is 15 minutes old; the %2B encoding a positive offset needs; and that a calendar date which does not exist is refused. realized-vol and commodities refuse as_of instead of ignoring it. §08's 400 row names the three as_of error codes. §09's point-in-time note lists the price and fundamentals series now captured on change and no longer says the as-of API is outside this surface. v1.12 · 2026-09-23: §04 gains meta.dataAsOf, the instant of the newest data point behind a payload's headline values. The public /status page now ages each feed from it against that series' own publication cadence, where it used to print the age of the cache fill, so a series older than its cadence allows reads stale rather than live. meta.dataAgeSeconds keeps its values; its description now says what it measures, the last write of the rows, which a re-fetch of unchanged values resets. On /v1/gas/pipeline-flows each point also carries the gas day its flow belongs to (Data Dictionary §9). v1.11 · 2026-09-23: §06's /v1/history/gas-storage gains the optional area parameter, so a country's fill is compared with that country's own five-year band. The product's storage overlay needed it: it had compared a country's current fill with a fixed February norm. The EU default is unchanged; GIE_UK is refused with the reason stated above. v1.10 · 2026-09-22: §03 described a surface key-gated in full, and production stopped matching it when the anonymous sample tier was switched on: measured 22 September 2026, 28 of the 29 documented paths answer a request carrying no key with 200 and a sample block, and /custom refuses it for want of a signed-in tenant. §03 now states the two tiers as measured and dated, and §05's history-window row follows. §03's at-rest sentence overreached (F-252): only keys issued as rows are held as a digest, while an entry on the break-glass list may be the token itself; the list now also accepts a digest form and the section says which is which. §07 said there was no per-key rate limit and no 429 from Voltstack; a per-key limit had shipped (F-334), and a per-address limit on requests carrying no key ships with this revision, so §07 documents both and §08 gains a 429 row. §08's 401 row is rewritten to the two refusals that remain. The v1.6 to v1.9 statements that every request carrying no key is refused are superseded. v1.9 · 2026-09-13: §06 gains /v1/gas/norway-events, the Gassco REMIT UMM events feed live at /api/feeds/gassco since 13 September 2026, with the payload documented field by field in Data Dictionary §22a; §01, §07 and §09 name it. Events only: the endpoint carries no Norwegian flow or nomination data and the coverage matrix says so. Two payload facts are stated because a reader would otherwise assume the opposite: capacity units are per message so there is no feed-level total, and data.events[] can carry a superseded message beside its revision so aggregation belongs on activeNowUnavailable. Documentation catch-up: no behaviour changed in this revision. v1.8 · 2026-08-27: §03 documents key scopes (history, current, all) and the 403 refusal a valid key receives on an endpoint its scopes do not cover, with the served insufficient-scope body printed; §08 gains the matching 403 row and the 401 row now points the short-scope case at it. Documentation catch-up: the shipped gate already refused short-scoped keys this way, and no behaviour changed in this revision. v1.7 · 2026-08-09: the §06 de-bess entry said "Public, no auth", which contradicted §03 inside this document and was false against the shipped gate, measured 401 unkeyed on every documented /v1 path. Removed: no §06 entry now states its own access rule, because access is set for the surface and §03 is where it is stated. The de-bess/custom entry now says its Professional-plan requirement is additional to §03 rather than an alternative to it. v1.6 · 2026-08-08: the §08 401 row said "history endpoints only", which v1.5 left standing when §03 withdrew the same claim. Every documented /v1 path refuses a keyless request, current feeds included, so §08 now says so and §03 states the observed gating rather than staying silent on it. The "keyless /v1" wording in the v1.3 note below is superseded on both counts. v1.5 · 2026-08-08: §03 withdraws the keyless-surface scope claim, which production replaced, and documents the shipped key mechanics instead (vsk_live_ token format, per-key identity, hashed at rest); the 401 example now prints the body the service actually returns. §09 corrects gas storage to six countries and weather to sixteen regions, and the §06 weather line follows; in each case one served id had never been documented, and the data dictionary §7 and §27 now name it. v1.4 · 2026-07-31: document version and date published as machine-readable meta tags (voltstack-doc-version, voltstack-doc-updated) and printed in the page header; the PDF edition is served alongside the HTML at /docs/. v1.3 — 2026-07-31: authentication rewritten to the shipped key model (keyless /v1; X-API-Key on history endpoints); day-ahead and flows payload examples corrected to the served shapes; error and rate-limit semantics corrected; envelope lastGood, areaStatus and the real reason enum documented; EUA primary auctions and the RTE FR generation forecast added to coverage. Specification subject to change during early access. Field names and coverage reflect the platform as at 2026-07-31. © 2026 Voltstack Limited.