Documentation

Quickstart

Get an API key from your dashboard, then make your first request. New here? The dashboard will guide you to sign in.

Base URL

REST endpoints under /v1 require an API key via the Authorization: Bearer YOUR_API_KEY header. This is a spot-price and reference-FX API, not a retail electricity bill.

Dates and times are UTC

Never interpret a Sparkrate timestamp as the server's, your browser's, or the bidding zone's local clock. Z means UTC. For example, 2026-09-27T14:00:00Z is the same instant everywhere; Copenhagen displays 16:00 on that summer-time date. Convert exactly once at the presentation boundary.

REST, MCP, and the Try-It examples use time_basis: "UTC". A date selects a UTC calendar day from 00:00:00Z inclusive to the next 00:00:00Z exclusive, not a zone-local day. today and tomorrow also mean UTC days. Invalid date queries return 400.

Daily responses include period_start_utc and period_end_utc. Hourly price arrays retain 24 hour/price entries, with full ISO 8601 start_utc/end_utc timestamps ending in Z on every entry. The short hour, min_hour, and max_hour labels are explicitly UTC. Unknown prices remain null; coverage may be partial even when some prices are available.

timezone is regional metadata only. Clients decide whether and how to display local times, including daylight-saving transitions. Current and upcoming intervals include their full UTC dates, even across midnight. Cheapest windows start no earlier than the next full UTC hour, never bridge missing hours, and return full ISO 8601 Z values in start/end and their start_utc/end_utc aliases. MCP cost estimates use the same whole-hour baseline.

Illustrative excerpt: the real hourly response has 24 UTC slots. A local calendar day may have 23 or 25 hours; request the UTC dates covering that local day and filter by full timestamps if you need a local-day view.

Compatibility note: routes and the legacy hour/price fields remain. UTC boundary fields are additive; cheapest_window.start/end now have explicit Z. Price placement is corrected to follow the source period's actual UTC start, so values can differ from older shifted lookups. Missing source intervals and missing currency conversion no longer become interpolated or mislabelled prices.

Raw energy periods

from and to are inclusive UTC calendar dates, limited to 31 days per request. Results retain original PT15M, PT30M, or PT60M periods with UTC ISO 8601 Z timestamps. This endpoint supplies spot prices and historical FX only: it does not include grid tariffs, taxes, or VAT.

fill_missing=true authorizes a bounded attempt to fetch missing data within the requested range. Actual coverage may remain partial; it does not guarantee complete data or synthesize missing prices. The existing /v1/prices hourly endpoints remain available unchanged in route and legacy field names.

Hole fetching is on by default; use fill_missing=false for a cache-only read. A request attempts at most six price days and six FX dates within a four-second fetch budget, with a short cooldown for repeated misses. It adds source observations without replacing known prices; an empty or partial response is still possible. FX dates identify the actual observation day, which can precede the requested date on weekends and holidays.

X-Sparkrate-Fill reports inline or cache-only.

Server-Timing separates auth, quota, fill, prices, fx, parse and usage where applicable. app is the total application time before response serialization and network transfer. All durations are milliseconds; timings do not contain API keys or user data.

The raw response uses camelCase fields: version, zone, from, to, timeBasis, periodStartUtc, periodEndUtc, generatedAtUtc, prices and exchangeRates. Each price contains its original periodStart, periodEnd, resolution, measureUnit, currency and point positions. Adjacent original periods may extend beyond the requested bounds; clip by UTC timestamps, not array indices.

This reference is static; the Try-It executor below does not implement the raw energy endpoint.

Endpoints

Supported Zones

43 European bidding zones across 31 countries — from the Nordics to the Balkans to Ukraine.

Supported Currencies

All 30 ECB currencies available for price conversion and the exchange rate API.

Zone currencies (top row) are used as defaults for each bidding zone. All currencies work with ?currency= on price endpoints. ECB rates updated daily, historical back to 1999.

MCP Server (AI Assistants)

Give compatible AI assistants electricity price tools via the Model Context Protocol (opens in a new tab).

Configuration

For VS Code, add this server to your MCP configuration. For other clients, use the same URL with their Streamable HTTP connection settings.

Available Tools

Example prompts

Rate Limits

REST limits apply per account across its API keys, including cached responses. Check X-RateLimit-Remaining-Day, X-RateLimit-Remaining-Month and X-RateLimit-Reset. See your actual usage in the dashboard and compare plans.