How the platform thinks
The platform keeps market data: prices, loads, forecasts. It keeps each value with two times, and it never overwrites one. Once you see why, every request in the other guides reads plainly.
The guide for readers of data: 1. How the platform thinks · 2. Reading data and building on it · 3. What stays the same · 4. What changed
A value has two times
Start with something you know. A weather forecast says: tomorrow at noon, 18 degrees. Two times are in that sentence. One is the time the forecast is for: tomorrow at noon. The other is the time it was made: this morning. Tonight's forecast for the same noon may say 16 degrees. Both forecasts are about one moment; they differ in when they were known.
Market data works the same way. Take one example and keep it for the whole
page. The series entsoe.de_lu_price holds the day-ahead price
for Germany and Luxembourg, a value for every quarter-hour. Look at the
quarter-hour that begins at noon in Berlin on Nov. 18, 2026. Suppose the
auction's result is published the day before, on Nov. 17 at 13:00 in Berlin,
and it says 85.30 euros a megawatt-hour.
The platform stores that value with both times:
| Field | Name | In the example | Means |
|---|---|---|---|
valid_at | Valid time | 2026-11-18T11:00:00+00:00 |
The moment the value is for. For a value that covers a period, the moment the period begins. |
known_at | Known time | 2026-11-17T12:00:00+00:00 |
The moment the value became known: when its source published it. |
value | Value | 85.3 |
What the source said. |
Noon in Berlin in November is 11:00 in UTC, and 13:00 is 12:00. The platform writes every time in UTC; Time and the market's day says why.
Why keep the known time at all? Because without it you cannot answer the question a trader or a model asks most: what did we know then? A forecast made at 10:00 on Nov. 17 could not have used a price published at 13:00. If the record forgot when each value became known, a test of that forecast against history would let it peek at the answer.
Reading as of a moment
Every read of values takes a moment called as_of. The
platform answers with what was known at that moment and nothing later. Leave
as_of out and it means now.
Read the example's quarter-hour three times, each as of a different moment on Nov. 17:
as_of | Berlin time | The answer holds |
|---|---|---|
2026-11-17T09:00:00Z | 10:00 | No value. Nothing was published yet, so the valid time is not in the answer at all; asked for every step (fill=step), it is there, null, its status not_due. |
2026-11-17T12:30:00Z | 13:30 | 85.3, known at 2026-11-17T12:00:00+00:00. |
| Absent | Now | The latest value known now. |
The second read, in full, is this request and this answer:
GET /v1/values?series=entsoe.de_lu_price
&start=2026-11-18T11:00:00Z&end=2026-11-18T11:15:00Z
&as_of=2026-11-17T12:30:00Z
{
"as_of": "2026-11-17T12:30:00+00:00",
"recorded_as_of": null,
"series": {
"entsoe.de_lu_price": {
"kind": "number",
"unit": "EUR/MWh",
"valid_at": ["2026-11-18T11:00:00+00:00"],
"known_at": ["2026-11-17T12:00:00+00:00"],
"value": [85.3],
"status": [null]
}
},
"next_cursor": null
}
The answer comes column by column: the first valid time goes with the
first known time, the first value and its status, the second with the
second, and so on, in the order of valid time. A period runs from start, included,
to end, excluded, so a day's read does not pick up the first
value of the next day.
The rule, then: for each valid time in the period, the answer
gives the latest value whose known time is not after as_of, and
says when it became known. A valid time with no such value is left
out.
A revision is a new version, never an overwrite
Go on with the example. Suppose that at 15:30 in Berlin on Nov. 17 the source corrects the price to 84.10. The platform does not change the value it stored. It stores a second version beside the first:
valid_at | known_at | value |
|---|---|---|
2026-11-18T11:00:00+00:00 | 2026-11-17T12:00:00+00:00 | 85.3 |
2026-11-18T11:00:00+00:00 | 2026-11-17T14:30:00+00:00 | 84.1 |
Both versions are for the same quarter-hour. They differ in when they became known. Now the three reads say:
as_of | Value | Known at |
|---|---|---|
2026-11-17T09:00:00Z | None | |
2026-11-17T12:30:00Z | 85.3 | 2026-11-17T12:00:00+00:00 |
| Absent, now | 84.1 | 2026-11-17T14:30:00+00:00 |
The read as of 12:30 UTC still answers 85.3, today and next year. That is the point of keeping versions: a correction tells you something new without erasing what you knew before.
Three things follow.
- One read gives one value for each valid time: the
latest known at
as_of. To see an earlier version, read with an earlieras_of. - The known time tells you a value was revised. A day-ahead price whose known time is hours after the auction was corrected.
- To test a model honestly, give it a cut-off. Read its inputs as of the moment it would have run, and it sees nothing that became known later.
The same read may hold more tomorrow. A stored value is never changed; but a value can be stored late. A feeder that was down on Tuesday reads its source on Thursday, and stores Tuesday's values with the time the source published them, which is Tuesday. A read as of Tuesday evening, made on Wednesday, lacked them; made on Friday, it holds them. So an as-of read never loses a value and never changes one, and it may gain some. A model, an indicator or a report must take the data it is given, and not suppose that the same read will count the same rows next week.
A series and its name
A series is one quantity followed through time: one market's day-ahead price, one zone's load forecast. Its name is how you ask for it.
A name is a namespace, a dot, and a local name. In
entsoe.de_lu_price the namespace is entsoe and the
local name is de_lu_price. The namespace says where the series
comes from, and it decides who may read it.
| Name | Comes from | Who reads it |
|---|---|---|
{namespace}.{name}, such as entsoe.de_lu_price |
A feeder: a program that fetches one source's data for the platform. A namespace belongs to one feeder for good. | Everyone who may read the platform's data. |
forecast.{model}.v{version}.{target}, such as forecast.naive.v1_0.epf.price |
A model's forecasts, kept as data. The version's dots are written as underscores; the target is the series it forecasts. | Everyone who may read the platform's data. |
ext.{username}.{name}, such as ext.tara.spread |
A person's own series. | That person alone. |
Each part of a name between dots is lower-case letters, digits and
_, and starts with a letter. A name is at most 200
characters.
A series you may not read is answered exactly as one that does not exist:
the error is unknown_series either way. The platform does not
tell names to those who may not read them.
The catalog, GET /v1/series, lists every series you may read.
For each it gives its kind, unit and currency, the market and the product
where the source names them, and where its values come from; asked with
view=full, also its description, its source, and three times
that tell you what it holds:
| Field | Means |
|---|---|
first_valid_at | The earliest valid time it holds a value for. |
last_valid_at | The latest valid time it holds a value for. For a day-ahead price this is ahead of now. |
latest_known_at | The latest known time among its values: when it last learned something. |
Each is null for a series that holds no value yet. Where the
source states them, the catalog also gives the series' card:
its grid, its time zone, when it publishes, and whether it revises.
Reading data lists the
fields.
Kinds and units
A series has a kind and a unit, and the catalog and every read state both.
- The kind is
number,textorarray. Prices, loads and forecasts are numbers. A value may benull: the source said there is none. - The unit is text, as the source gives it, such as
EUR/MWh. The platform does not convert units. An indicator that takes several inputs refuses inputs whose units differ, so that it never subtracts megawatts from euros.
Some series carry an estimate of error beside each value: a forecast with
its standard deviation, say. A read of such a series with
view=full has one more object, estimates, with a
column for each estimate the series declares, such as std, as
long as value, and null where a value has
none.
Time and the market's day
Every time is an instant, with its offset
The platform works in instants: moments that mean the same everywhere.
You write a time with its offset from UTC, as
2026-11-18T11:00:00Z or, the same instant,
2026-11-18T12:00:00+01:00. A time without an offset, such as
2026-11-18T12:00:00, is refused with invalid_time:
the platform will not guess which noon you mean.
The platform always answers in UTC, written with
+00:00: 2026-11-18T11:00:00+00:00.
A market's day is 23, 24 or 25 hours
Markets count their days in local time. Germany's trading day runs from midnight to midnight in Berlin. In UTC that is 23:00 to 23:00 in winter and 22:00 to 22:00 in summer. So the day of Nov. 18, 2026 is this period:
start=2026-11-17T23:00:00Z&end=2026-11-18T23:00:00Z
Twice a year the clocks change, and the day changes length with them:
| Day in Berlin | Start, UTC | End, UTC | Hours | Quarter-hours |
|---|---|---|---|---|
| Nov. 18, 2026 | 2026-11-17T23:00:00Z | 2026-11-18T23:00:00Z | 24 | 96 |
| March 28, 2027 | 2027-03-27T23:00:00Z | 2027-03-28T22:00:00Z | 23 | 92 |
| Oct. 31, 2027 | 2027-10-30T22:00:00Z | 2027-10-31T23:00:00Z | 25 | 100 |
This is why the platform stores instants and not local times. On Oct. 31, 2027 the hour from 02:00 to 03:00 happens twice in Berlin. In UTC the two are different instants, and each has its own price.
The rule for your code: never find a day by adding 24 hours. Find midnight in the market's zone, with a time-zone library, and convert it to UTC. The same goes for the count of values in a day: take it from the data, not from a constant. A series may also change its step; ENTSO-E's day-ahead prices for Germany have come in quarter-hours since October 2025, where they came by the hour before.
The platform's indicators follow the same rule. A compute takes a
zone, Europe/Berlin unless you say otherwise, and a
step of a day, P1D, is that zone's day, of 23, 24 or 25
hours.
Timelines
So far every read was of the real record: what real sources published,
when they published it. The platform calls that record the timeline
live. It is the default of every read, and most readers never
name another.
There is one other thing a timeline can be: a simulation,
a replay of a past period that belongs to one person. Its name begins with
its owner's user name: tara.backtest is tara's. What happens in
a simulation stays in it and never mixes into live.
The read API exposes timelines this far and no further:
- The catalog, a read of values and a compute of one of the platform's
indicators each take
timeline. Absent, it islive. - A person may name a simulation of their own. The read then sees
liveand that simulation together: for each valid time, the latest value known on either. - Naming anyone else's timeline is refused: status 403, code
timeline_not_allowed. - The stream of changes tells changes on
livealone. - A call of a person's model or indicator takes no timeline.
In short
- A value is for a time,
valid_at, and became known at a time,known_at. - A read is as of a moment,
as_of: the latest value known by then, for each valid time. Absent, now. - A revision adds a version. Nothing stored is overwritten.
- A name is a namespace and a local name. The namespace says whose the series is.
- Times are instants with an offset; answers are in UTC. A market's day is its zone's day, and not always 24 hours.
- The real record is the timeline
live.
Next: Reading data and building on it puts these ideas to work, one request at a time. The read API's reference lists every request and field.