Specs

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:

FieldNameIn the exampleMeans
valid_atValid time2026-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_atKnown time2026-11-17T12:00:00+00:00 The moment the value became known: when its source published it.
valueValue85.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_ofBerlin timeThe answer holds
2026-11-17T09:00:00Z10: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:00Z13:30 85.3, known at 2026-11-17T12:00:00+00:00.
AbsentNow 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_atknown_atvalue
2026-11-18T11:00:00+00:002026-11-17T12:00:00+00:0085.3
2026-11-18T11:00:00+00:002026-11-17T14:30:00+00:0084.1

Both versions are for the same quarter-hour. They differ in when they became known. Now the three reads say:

as_ofValueKnown at
2026-11-17T09:00:00ZNone
2026-11-17T12:30:00Z85.32026-11-17T12:00:00+00:00
Absent, now84.12026-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.

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.

NameComes fromWho 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:

FieldMeans
first_valid_atThe earliest valid time it holds a value for.
last_valid_atThe latest valid time it holds a value for. For a day-ahead price this is ahead of now.
latest_known_atThe 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.

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 BerlinStart, UTCEnd, UTCHoursQuarter-hours
Nov. 18, 20262026-11-17T23:00:00Z2026-11-18T23:00:00Z2496
March 28, 20272027-03-27T23:00:00Z2027-03-28T22:00:00Z2392
Oct. 31, 20272027-10-30T22:00:00Z2027-10-31T23:00:00Z25100

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:

In short

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.