From f99bcf4d43f61ece45af9ad1215473d1a19028cf Mon Sep 17 00:00:00 2001 From: Sebastian Lerner Date: Thu, 6 Aug 2026 16:58:34 -0400 Subject: [PATCH 1/3] Consolidate v8/v11 timestamp monotonicity docs into one branch Same root cause (median timestamp over configured data providers), same fix pattern (expect advancement as the norm; a single stalled or backward-moving report is expected and fine on its own; only escalate if it recurs across multiple consecutive reports or exceeds your own staleness threshold). No reason to ship this as two separate branches. --- .../data-streams/reference/report-schema-v8.mdx | 11 +++++++++++ .../rwa-streams/24-5-us-equities-user-guide.mdx | 11 +++++++++++ 2 files changed, 22 insertions(+) diff --git a/src/content/data-streams/reference/report-schema-v8.mdx b/src/content/data-streams/reference/report-schema-v8.mdx index 5380ba67799..9437dcfec4c 100644 --- a/src/content/data-streams/reference/report-schema-v8.mdx +++ b/src/content/data-streams/reference/report-schema-v8.mdx @@ -32,6 +32,17 @@ RWA streams adhere to the report schema outlined below. indicate when data was last recorded, not whether the market is currently active. + + v8 streams use a three-value mapping: | Value | Status | Description | diff --git a/src/content/data-streams/rwa-streams/24-5-us-equities-user-guide.mdx b/src/content/data-streams/rwa-streams/24-5-us-equities-user-guide.mdx index 8e0f2f30a89..d5441c1d83a 100644 --- a/src/content/data-streams/rwa-streams/24-5-us-equities-user-guide.mdx +++ b/src/content/data-streams/rwa-streams/24-5-us-equities-user-guide.mdx @@ -136,6 +136,17 @@ Consumers must treat `marketStatus = 5` (Closed) as a valid state and define det Markets may stop updating due to exchange outages, circuit breakers, trading halts, or corporate actions. The `marketStatus` field will continue reflecting the status that it normally would. Use the `lastSeenTimestampNs` field (which reflects the timestamp of the last update for the `mid` price only) to detect staleness by comparing it against the current time. When this timestamp stops advancing, it indicates the underlying venue has stopped providing updates. +##### Why `lastSeenTimestampNs` can pause, or move non-monotonically, without an outage + +`mid` and its timestamp `lastSeenTimestampNs` are derived from a consensus across the data providers configured for a feed, and both only update when that consensus changes. Two related behaviors follow from this, especially on feeds configured with a small number of data providers: + +- **Pausing:** Individual data providers do not all publish at the same rate — some sourcing venues naturally have lower update frequency during certain windows, particularly for less liquid names or during thinner trading periods. When enough providers are momentarily quiet, the consensus value — and its timestamp — can hold steady for longer than you might expect, even though the DON is healthy and continuing to produce reports. +- **Non-monotonic movement:** Which providers are actually included in a given report can also change from one report to the next, for example if a provider times out on one report and returns on the next. Because the timestamp is derived from whichever providers are included, it is not guaranteed to strictly increase — it can occasionally shift to an earlier value than the previous report's timestamp. + +In the normal case, expect `lastSeenTimestampNs` to advance in line with the update cadence for a given symbol and session. Brief exceptions — a momentary pause or an occasional shift to an earlier value — are a known consequence of provider-side availability on low-DP-count feeds, not a sign that the feed or DON is down, and a single occurrence is not by itself cause for concern. + +A single stalled or backward-moving report is expected and not, by itself, cause for concern. Treat it as a potential issue only if the behavior recurs across multiple consecutive reports, or the pause exceeds your own configured staleness threshold (see the staleness check example in [Stream Switching Example Logic](#stream-switching-example-logic)). At that point, apply your staleness safeguards regardless of whether the eventual cause turns out to be provider behavior or something else. Do not assume `lastSeenTimestampNs` strictly increases between reports. + Phase-specific feeds can introduce unique behavior due to venue-specific operational characteristics and market microstructure. The following are some examples of scenarios that may occur during session transitions or under specific market conditions: ##### Regular Hours Session: Delayed Quote Availability at Market Open From 6aca686988c34c39dbcebeed4e22b31e37b2d416 Mon Sep 17 00:00:00 2001 From: Sebastian Lerner Date: Thu, 6 Aug 2026 17:39:14 -0400 Subject: [PATCH 2/3] Stop recommending observationsTimestamp as a freshness fix observationsTimestamp reflects report generation time, not confirmation that the underlying price changed, so it doesn't actually solve the freshness question. The recommendation stays lastUpdateTimestamp: reliable in the normal case, not bulletproof on low-DP feeds, with reliability improvements in progress. --- .../reference/report-schema-v8.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/data-streams/reference/report-schema-v8.mdx b/src/content/data-streams/reference/report-schema-v8.mdx index 9437dcfec4c..739efd2e650 100644 --- a/src/content/data-streams/reference/report-schema-v8.mdx +++ b/src/content/data-streams/reference/report-schema-v8.mdx @@ -32,15 +32,15 @@ RWA streams adhere to the report schema outlined below. indicate when data was last recorded, not whether the market is currently active. -