Market-data timestamps are not formatting details. They decide whether a quote was available before a signal, whether a bar belongs to premarket or regular trading, whether a WebSocket row is stale, and whether a backtest is using information from the future.
This guide defines the timestamp and session vocabulary CuteMarkets uses across stocks, options, REST APIs, WebSocket workflows, caches, and replay artifacts. Pair it with Market Data Access Methods, Market Data Ingestion and Caching, Quotes, Trades, and Aggregates, Live, Delayed, and Entitlements, and Historical Options Replay Runbook.
Core terms
| Term | Meaning |
|---|---|
| Event timestamp | The time attached to a trade, quote, bar, stream update, or calculated value |
| Request timestamp | The time your application requested data from the API |
| Decision timestamp | The time a strategy or user made a decision |
| Bar open timestamp | The start of an aggregate interval |
| Bar close timestamp | The end of an aggregate interval |
| Market timezone | The session timezone used to interpret regular hours, premarket, after-hours, and holidays |
| UTC | Coordinated Universal Time, useful for storage and cross-region systems |
| ET | Eastern Time, the practical session timezone for U.S. equities and listed options |
| Quote age | The difference between decision time and the latest usable bid/ask quote |
| Stale threshold | The maximum acceptable age before data is labeled stale or rejected |
| Session label | A tag such as premarket, regular, after-hours, closed, holiday, or unknown |
UTC for storage, ET for session reasoning
Store timestamps in UTC whenever possible. Convert to Eastern Time when the workflow needs to reason about U.S. market sessions. This avoids ambiguous daylight-saving transitions and keeps distributed systems consistent.
A clean artifact stores both:
{
"event_timestamp_utc": "2026-06-04T15:31:42.120Z",
"event_timestamp_et": "2026-06-04T11:31:42.120-04:00",
"session_label": "regular",
"market": "US_OPTIONS",
"source": "quotes",
"timezone_policy": "store_utc_display_et"
}
The same policy applies to Options Quotes, Options Trades, Options Aggregates, Stock Trades and Quotes, and Stock Aggregates and Indicators.
Session labels
Market sessions need explicit labels because "today" is not enough. U.S. stock workflows can involve premarket, regular hours, after-hours, half days, holidays, and overnight gaps. U.S. listed-options workflows generally focus on regular hours, with some products and venues having special behavior.
Use a session label in every live dashboard, scanner, and backtest artifact:
| Label | Use |
|---|---|
premarket | Stock activity before regular session where supported |
regular | Main U.S. market session |
after_hours | Stock activity after regular session where supported |
closed | No active session for the product |
holiday | Market holiday or special closure |
half_day | Shortened session |
unknown | Provider or application cannot classify the timestamp |
Do not copy stock session assumptions directly into options workflows. If an options strategy depends on exact session behavior, record the product, venue assumption, and data object. A stock bar in premarket can trigger a watchlist event, but an option quote window may still be unavailable or irrelevant for the intended fill.
Quotes, trades, and bars use timestamps differently
The same timestamp string means different things depending on the object:
| Object | Timestamp meaning | Common mistake |
|---|---|---|
| Quote | When the bid/ask market update was observed or effective | Treating an old quote as current |
| Trade | When a transaction print occurred | Treating the print as a fillable market later |
| Aggregate | The time window represented by the bar | Filling inside a bar after using completed-bar information |
| Snapshot | Current state assembled from recent fields | Treating latest state as a historical replay |
| Indicator | The bar window used to calculate the value | Using an indicator value before its input bar closed |
| WebSocket event | Stream update arrival or event time depending on field | Treating client receipt time as market event time |
For options execution realism, the critical value is quote age. A strategy decision at 10:15:00 ET should not fill from a quote last updated at 10:09:00 ET unless the policy allows it and the artifact says so. See Backtesting Execution Realism, Why Option Quotes Matter More Than Last Price, and Quote-Aware Options Backtests.
Completed bars and same-bar risk
Completed bars create a common lookahead bug. If a signal uses a completed 5-minute stock bar ending at 10:35:00 ET, the decision cannot also claim an option fill at 10:33:00 ET from inside that same bar. The strategy did not know the bar outcome at 10:33.
A safer artifact stores:
- signal bar start
- signal bar end
- decision timestamp
- next observable quote timestamp
- quote age
- fill timestamp
- fill policy
- reject reason if the first available quote fails
Use Same-Bar Fill Lookahead, Backtesting Engine Loop, Stock and Options Data Join Workflow, and Historical Market Data Ingestion and Cache Design for the implementation path.
WebSocket timestamps
Live systems need to separate event time from client time:
- event timestamp from the data record
- server receive timestamp where available
- client receive timestamp
- last heartbeat timestamp
- last reconnect timestamp
- last REST backfill timestamp
A row can be live by plan but stale by event age. A WebSocket can be connected but still behind if the topic has not received an event. That is why WebSocket docs, REST vs WebSocket Market Data API Guide, and Real-Time Options System Design include freshness labels and reconnect backfills.
Historical replay timestamp checklist
Before trusting a historical replay:
- Store the event timestamp in UTC.
- Convert it to ET for session classification.
- Record the decision timestamp separately from request timestamp.
- Confirm whether aggregate timestamps refer to bar open or bar close.
- Confirm quote age at entry and exit.
- Store the first usable quote after the decision.
- Record empty quote windows as rejects.
- Preserve pagination state for dense quote or trade windows.
- Store live, delayed, historical, cached, or backfilled labels.
- Attach the replay manifest to the result.
This checklist belongs in Historical Options Data API, Options Backtesting API, Backtesting Data Quality Checklist, and Market Data Corrections and Missing Data.
UI labels
User-facing applications need language that prevents overclaiming:
| Label | Meaning |
|---|---|
| Live quote | Current plan and endpoint support live quote access |
| Delayed quote | Quote is delayed by plan or feed |
| Stale quote | Quote exists but is older than policy |
| Historical quote | Quote was requested for a past window |
| Backfilled quote | Quote came from REST repair after a live gap |
| No usable quote | Quote is missing, stale, no-bid, or outside policy |
| Bar signal | Signal came from a completed aggregate interval |
| Session closed | Product session is not active for the timestamp |
The UI label can link to Live, Delayed, and Entitlements, Quotes, Stock Trades and Quotes, and Market Data Licensing and Commercial Use.
Related reading
- Market Data Access Methods
- Market Data Ingestion and Caching
- Market Data Corrections and Missing Data
- Historical Options Replay Runbook
- Stock and Options Data Join Workflow
- Market Data Timestamps and Trading Sessions API Guide
Timestamp implementation notes
Timestamp handling needs separate fields for request time, exchange or SIP timestamp, application receive time, bar start, bar end, and decision time. A stock signal and option quote may share a calendar date while still being unusable together. Store the exact timestamp that caused the next request, especially when joining Stock Aggregates and Indicators to Option Chain.
Market-session labels also matter. Premarket, regular session, after-hours, holiday, half-day, halted, delayed, and stale states can all change how a scanner interprets a row. Pair this page with Live and Delayed Entitlements and Backtesting Execution Realism before using quote age or completed bars in a fill model.