Skip to main content
Every Voltpath API response follows the same envelope shape: a meta object that describes provenance, time range, and resolution, plus a data array containing the endpoint-specific payload rows. Understanding this envelope helps you verify what the server resolved and how the data was produced.

​
The envelope

A typical response looks like this:
​
string
required
Whether the data is directly measured or computed:
  • measured - raw data from upstream sources such as ENTSO-E
  • derived - computed from other signals, such as flows calculated from prices and scheduled exchanges
​
string | null
The applied aggregation resolution: native, 1H, 1D, or 1W. null only on endpoints that don’t accept a resolution parameter at all (/flow-duration, /price-kpis, /zone-import-export) — it is never null for native data, which reports the literal string "native".
​
datetime | null
The UTC start datetime the server actually used after resolving relative shortcuts.
​
datetime | null
The UTC end datetime the server actually used after resolving relative shortcuts.
​
string[] | null
A list of upstream data sources, for example ["ENTSO-E Transparency Platform"].
​
object | null
Present only on /flows; null on every other endpoint. See Pagination below.
​
array
The payload rows. The exact schema varies by endpoint.

​
Datetime parameters

You can specify time ranges using either absolute ISO 8601 datetimes or relative shorthand. Absolute format:
Relative shorthand:
  • now - current UTC time
  • now-30d - 30 days ago
  • now-7d - 7 days ago
  • now-1H - 1 hour ago
  • now-15m - 15 minutes ago
All datetimes are resolved to UTC. When you use relative shorthand, the exact boundaries depend on when the server processes the request. Always check resolved_datetime_from and resolved_datetime_to in the response meta to confirm the actual range used.

​
Resolution

The resolution query parameter controls how data is aggregated. Available options:
  • auto (default) - the server selects a resolution based on the width of the date range. Recommended for most use cases.
  • native - raw data. Capped to a 2-day range: a wider explicit native request returns 422 instead of running.
  • 1H - hourly aggregation. Capped to a 14-day range for the same reason; wider explicit 1H requests also return 422.
  • 1D - daily aggregation
  • 1W - weekly aggregation
The caps on native and 1H only apply when you set them explicitly. auto is the escape hatch for wider ranges — it downgrades resolution as the range widens (native up to 2 days, 1H up to 14 days, 1D up to 90 days, 1W beyond that) instead of failing, so it never needs a cap of its own.
Resolution is not available on /api/v1/flow-duration, /api/v1/price-kpis, and /api/v1/zone-import-export.

​
Pagination

GET /api/v1/flows accepts limit (1–20,000, default 20,000) and offset (default 0). Rows are ordered by (datetime, bidding_zone_from, bidding_zone_to, flow_type) before slicing, so page boundaries are stable across requests. meta.pagination reports the unsliced row count:
No other endpoint paginates — their meta.pagination is always null. To pull a full result set, page while offset + limit < total, incrementing offset by limit each request. Pin datetime_from/datetime_to to absolute ISO timestamps first: the now-30d/now relative defaults re-resolve on every request, so the window — and total — would shift underneath a multi-page walk.
Pagination caps response size, not fetch cost or latency. The full range is still fetched and resampled server-side on each cache miss, and the API’s 30-second request timeout still bounds how wide a single request’s range can be, regardless of resolution or paging. For a multi-month pull, chunk the date range client-side (monthly is reasonable) and page within each chunk.

​
Rate limits

Requests are limited per API key: capacity 200, refilled at 120/min (2/sec). A request over the limit returns 429 with a Retry-After header giving the exact number of seconds to wait — scripts doing bulk pulls should sleep on that value directly rather than guessing or backing off.

​
Interpolated flag

Some rows include an interpolated or flow_interpolated boolean. When this flag is true, the value was estimated to fill a gap in the upstream data rather than directly observed.
  • PriceRow: interpolated indicates a gap-filled price
  • FlowTypeRow: flow_interpolated indicates a gap-filled flow
When building analytics or trading models, consider treating interpolated values with appropriate caution, since they are modeled rather than measured.

​
Error responses

When query parameters fail validation, the API returns a 422 Validation Error with a standard error body.

​
Example 422 response

The detail array contains one or more error objects with the following fields:
​
array
required
The location of the invalid input, typically ["query", "<parameter_name>"].
​
string
required
A human-readable description of what went wrong.
​
string
required
The error type classification, for example enum for invalid enum values.