Time and sessions

How do you read when a bar happened, on the right clock, and tell whether it falls inside a session? time is the bar's open and time_close its close, both in UNIX milliseconds. The date fields, such as hour and dayofweek, read the exchange's clock unless you name a zone, and time() with a session string is na outside that session.

//@version=6
indicator("New York session", overlay = true)
string sess = input.session("0930-1600", "Session")
// na outside the session; the zone says whose clock the hours use
bool inSession = not na(time(timeframe.period, sess, "America/New_York"))
bgcolor(inSession ? color.new(color.blue, 90) : na)
plot(hour(time, "America/New_York"), "Hour in New York",
     display = display.data_window)

A bar's times

Name	Holds
time	When the bar opens, in UNIX milliseconds
time_close	When the bar closes, on the symbol's schedule
time_tradingday	00:00 UTC of the trading day the bar belongs to
last_bar_time	time of the run's last bar
timenow	The wall clock as the script runs

A bar's close comes from the symbol's schedule, not from the next bar's open. A share's daily bar closes at 16:00 New York time, which is 21:00 UTC in winter and 20:00 UTC in summer, and at 13:00 on an early-close day such as 3 July 2024. In general, a daily bar closes at the end of the first session that ends after the bar's open time. A coin trades all day every day, so its daily bar lasts 24 hours.

time(tf) and time_close(tf) read the open and the close of the bar of timeframe tf that holds this one, so time_close("1W") is when this week closes. On a share whose Friday is a holiday, that's Thursday's close.

Time zones

year, month, weekofyear, dayofmonth, dayofweek, hour, minute and second read the bar's open on the exchange's clock, the zone syminfo.timezone names: America/New_York for a US share, Etc/UTC for a coin. So on a share's daily chart, hour is 9 and minute is 30, the session's open.

Each one also takes a time and a zone, as in hour(time, "Europe/London"), and follows daylight saving: for a bar opening at 13:30 UTC, that reads 13 on 28 March 2024, before British Summer Time starts, and 14 on 1 April.

timestamp builds a time. Its number form, timestamp(2024, 3, 28, 9, 30), is on the exchange's clock unless you pass a zone first, as in timestamp("UTC", 2024, 3, 28, 9, 30). Its date-string form, timestamp("2024-03-28") or timestamp("2024-03-28T09:30:00"), reads a string with no zone as UTC.

//@version=6
indicator("From a date", overlay = true)
// A date string with no zone is UTC, whatever the symbol's exchange
int start = input.time(timestamp("2025-01-01"), "Start")
plot(time >= start ? close : na, "Close since the start",
     style = plot.style_linebr)

The chart's time axis shows times in the terminal's reference zone, UTC unless you choose another. That changes what you see on the axis, never what a script reads.

Sessions

A session string lists the hours a session covers, as "0930-1600". Digits after a colon name the days, from 1 for Sunday to 7 for Saturday, so "0930-1600:23456" is Monday to Friday. With no days named, the session runs every day. Several ranges go with commas, as "0930-1200,1300-1600", and "0000-0000" is the whole day.

time(timeframe.period, sess, zone) gives the bar's time when the bar opens inside the session, and na when it doesn't, so not na(time(...)) is the test for "in session". Name the zone, or the hours are on the exchange's clock. input.session gives the user a field for the string.

Use that test, not the session.is* flags: here session.ismarket is always true, and session.ispremarket, session.ispostmarket, session.isfirstbar and session.islastbar are always false. For a session's first bar, use timeframe.change("1D").

Schedules and holidays

Every symbol's bars close on its schedule. A US share or index takes the New York Stock Exchange's calendar as TradingView has it, with its holidays and early closes. A few other symbols whose TradingView details the terminal holds take their own TradingView schedule. A symbol of another exchange takes that exchange's regular hours, and a symbol with no exchange hours, such as a coin, trades all day every day on UTC's clock.

The schedule decides time_close, time_close(tf), and when another symbol's bar becomes known to request.security, so a holiday moves all three together. Other symbols and timeframes has the rule.

Writing a time as text

str.format_time(time, pattern, zone) writes a time as text. With no zone it takes the exchange's.

Letters	Write	Example
yyyy, yy	The year	2024, 24
MMMM, MMM, MM, M	The month	March, Mar, 03, 3
dd, d	The day of the month	09, 9
HH, H	The hour, 0 to 23	14
hh, h, a	The hour, 1 to 12, and AM or PM	02, 2, PM
mm, ss	Minutes and seconds	05, 07
Z, z	The zone's offset and its short name	-0500, EST
'T'	The text between the quotes, as it is	T

Day names such as EEE aren't supported here: the letters come back as they are.

Traps

• The session.is* flags don't follow the session here: see Sessions.
• hour on a share's daily bar reads its open, 9:30 in New York, not its close.
• timenow moves with the clock, so a plot that reads it draws differently each time the script runs.
• time is a bar's open. To ask whether a moment has passed by the end of a bar, compare it with time_close.

See also

• Inputs, for input.time and input.session
• Strings and formatting, for str.format and its dates
• Other symbols and timeframes, for another timeframe's bars
• Time in the reference, for every time function's parameters