How Report Timestamps Work
Every Data Streams report carries two timestamps:
validFromTimestamp— when the report's price starts being validobservationsTimestamp— when the report's price was last observed.
Together, they describe a window of time rather than a single instant. This page explains how the two timestamps define a report's window, what to expect when no report exists for a given moment, and how they apply to TWAP streams.
Report windows
A report does not have verified price for a single instant in time. The validFromTimestamp marks the beginning of the window, and the observationsTimestamp marks the end.
Both fields are Unix timestamps in seconds. Each report schema contains definitions, including the unit of time, for all fields.
The window of time can vary depending on how frequently the Decentralized Oracle Network (DON) can observe the data and generate reports. Windows are contiguous by construction: each one starts immediately following the previous window. Each report is designed to have no gaps or overlap, with every time interval belonging to exactly one report.
Determining current price
Because each report covers a window rather than an instant, the "current" price at any given moment is the price of the report whose window contains that moment. Whether such a report exists yet depends on how recently the DON observed the data and delivered the report.
Normal case: a report exists at that exact moment
For example, a report exists with observationsTimestamp = 12:05:00 and a 1-second window. The report is delivered slightly after 12:05:00 (for reports with second-precision timestamps, typically up to 1-2 seconds later) due to DON consensus and transmission.
Edge case: no report at that exact moment
It is possible for no report to be observed with observationsTimestamp = 12:05:00. For example:
- Last report:
observationsTimestamp = 12:04:59 - Next report:
observationsTimestamp = 12:05:01
The next report's validFromTimestamp is 12:05:00, absorbing the gap and creating a 2-second window (12:05:00 → 12:05:01). In this example, the price for 12:05:00 is observed one second later at 12:05:01.
Because windows can vary in width, do not assume every report covers the same window. Read validFromTimestamp and observationsTimestamp from each report rather than deriving the window from the previous report's timestamp or from your own clock.
TWAP streams
TWAP streams aggregate the reports in a rolling window rather than publishing a single observed price. See TWAP Streams for the window mechanics and formula.