Times, dates, and sessions

How can I get the time of the first bar in the dataset?

The following example script initializes a variable using the var keyword on the first bar and then never updates it again. The variable stores the value of the time built-in, which represents the time of the bar open in UNIX format (milliseconds since 00:00:00 UTC on 1 January 1970).

How can I convert a time to a date-time string?

The built-in function str.format_time() translates a UNIX timestamp into a string representation of date and time. In the following example script, we provide four distinct methods to obtain the date-time string, two of which offset the date and time into the future. To improve readability, we use a custom function, timeToString(), which calls str.format_time() and applies a consistent format, instead of specifying the format for every function call.

The format "YYYY.MM.dd @ HH:mm:ss" is similar to the ISO 8601 date and time representation, but with periods to separate parts of the date, and an @ symbol between the date and time. For more formatting customization options, consult the str.format_time() documentation.

How can I find out how many days are in the current month?

The following example script calculates the number of days in the current month, including adjustments for leap years. By default, the daysPerMonth() function uses the current year and month, but any year or month number can be passed as arguments:

How can I detect the chart’s last day?

Scripts can detect the last day on a chart in different ways. However, because the last_bar_time and timenow variables constantly update to mirror the time of the newest bar, each subsequent realtime bar is also interpreted as if it is the chart’s last day.

Using ​timeframe.change​

This example script checks for all of these conditions:

• The daily timeframe begins a new day.
• The difference between the time of the last chart bar (retrieved using last_bar_time) and the current bar’s time (from time) is less than the time in one day.

The script colors the background red on the last day.

Using ​timenow​

This script uses the timenow variable to retrieve the current time — not the time of the bar on which the script is executing, but the time of the latest chart update. We pass this time as input to the built-in functions year(), month(), and dayofmonth() to calculate the year, month, and day of the month for that time. We compare these calculated values with the built-in variables year, month, and dayofmonth, which store the year, month, and day of the month of the current chart bar. When the year, day and month of the latest chart update match the values of the current bar, then the script is executing on bars from the most recent day.

How can I plot a value starting n months or years back?

The timestamp() function can accept negative argument values and convert them to accurate dates. For instance, a negative month value deducts the corresponding number of months from the outcome.

Our example script calculates the date three months prior to the current time, using the timestamp() function to create a timestamp that is the configured amount of time prior to the time now, as measured using timenow. As the script executes on each bar, it compares the bar time with the previously calculated timestamp. When the time of a bar matches our specified target date, we assign the high of that bar as our value to plot and color the background red for demonstration.

How can I track highs and lows for a specific timeframe?

The following example script tracks the high and low values of a timeframe that the user selects. Our script avoids using request.security() calls, which are resource-intensive.

Note that:

• We detect the beginning of a new timeframe by passing the period input to the timeframe.change() function.
• The script resets the hi and lo variables at the beginning of a new timeframe and then trails hi up and lo down.
• We change the color of plots to na every time a new timeframe begins, to visually distinguish between periods.

How can I track the highs and lows within a specific session or time of day?

To find if a time is within a specific session, pass a session string to the time() function, which retrieves the UNIX time of the current bar based on a given timeframe and session. If the time point falls outside the session, the function returns na.

In the following example script, on the first bar that the time is in session, we set the hi and lo variables to the source inputs provided by the user (high and low by default). During the session we trail the hi value up and the lo value down. The script also highlights the background red when a bar’s time falls outside the session time.

Note that:

• We use the 3-parameter version of the time() function to ascertain whether we are within user-specified hours and timezone for tracking highs and lows.
• We pass a session input and an optional timezone to the time() function.

How can I track highs and lows for periods within a bar?

Historical bars contain one set of OHLC data for each bar. To identify values and times that start or end within a chart bar, intrabar inspection is necessary, using data from lower timeframes.

For instance, on an hourly chart, the market open might occur mid-bar, making it hard to determine pre-market highs and lows. Pulling data from a lower timeframe, such as a 15-minute chart, provides a clearer view of that hour’s events.

The following example script calculates pre-market highs and lows from 15-minute chart data.

• First, we define a function called hiLoBetweenTime() to track the highs and lows within a session.
• Next, we modify the symbol’s ticker using ticker.modify() to include extended session data, ensuring that the script identifies premarket highs and lows even when the chart uses regular trading hours.
• Finally, we pass the hiLoBetweenTime() function as the expression of the request.security() function, with the modified ticker as the symbol. The request.security() function evaluates the hiLoBetweenTime() function within the context of the lower timeframe to calculate the session’s highs and lows.

Note that:

• The script raises an error using runtime.error() if the chosen lower timeframe for intrabar inspection is not shorter than the main chart’s timeframe. Including error-checking such as this when working with timeframes makes the script more robust.

How can I detect a specific date and time?

The simplest way to detect a specific date and time is to check the time variable, which returns the timestamp of the current bar’s open. If this matches a certain timestamp, then the script has detected that specific date and time.

The following example script colors the background green when the chart time exactly matches a date and time that the user inputs.

However, matching an exact date and time is not very useful. If the target time does not coincide with the opening of a candle on the chart timeframe, then that exact time never matches. For example, if the user specifies “2025-03-24 10:01” as the target time for the script above, then it never matches on any timeframe above one minute.

The following script behaves more intuitively, by coloring the background if a target time input by the user falls anywhere within a particular chart bar. The script colors one and only one bar even if the time does not match the open of a bar. The days, hours, and minutes are all tested separately to see if they match the target time, and these boolean conditions must all be true in order for the background to be colored. If the chart timeframe is too high, we set the corresponding lower time conditions to true so that they do not prevent the overall condition from firing. For example, if the timeframe is one day or above, we bypass the isTargetHour condition by setting it to true without evaluating the number of hours.

Note that:

• The script does not work on timeframes less than one minute, because the time input does not use seconds. The script could be extended to work on timeframes of one month and higher.
• We use confirm = true for the time input, which prompts the script user to select a date and time when the script first loads on the chart. The time selected in this way is always equal to the time of the selected bar’s open, but the user can change it in the “Settings” window.
• We use the built-in variables year, month, dayofmonth, hour, and minute, which store the time of the current bar’s open.
• We use the built-in functions year(), month(), dayofmonth(), hour(), and minute() to retrieve the time of the current bar’s close, and to evaluate the time that is input by the user.

How can I know the date when the highest value was found?

To determine the date on which the highest value occurred, the following example script uses the ta.highest() function to find the highest value within a certain lookback period, and the ta.highestbars() function to find how many bars back this value occurred. If the highest point occurs on the current bar, the number of bars back, or offset, is zero. In our example script, when this condition is met, we update labels showing the time at the respective highest or lowest price.

Note that:

• We declare the high and low labels with var but supply na values for the x and y coordinates, so that the labels do not appear until these parameters are defined.
• When the bar offset functions return zero, we modify the respective label to display the bar time.
• The script plots the highest and lowest level for visual reference.

How can I detect bars opening at a specific hour?

The following example script demonstrates three methods for detecting bars that open at 18:00 hours:

Check the current bar’s time

We check whether the built-in hour variable is equal to eighteen and the minute variable is equal to zero.

Detect the start of the session

Using the time() function with a session string returns the time of the current bar if it is within the session time. If it’s outside the session time, the function returns na. We determine the first bar that falls within the session by verifying that the current returned time is not na but was na one bar earlier.

Check current time against a timestamp

We generate a timestamp using the timestamp() function by specifying 18 hours and 0 minutes, as well as the current day, month, and year. We then verify whether the bar’s time matches this timestamp.

Note that:

• To ensure that the numbers do not plot on top of one another, we use the technique described in the FAQ entry How can I stack plotshape text?

Can I time the duration of a condition?

Normally, variables reset every time the script performs a new iteration. This process is called rollback and is described in the Execution model page of the User Manual.

By contrast, variables declared with varip preserve their values between realtime updates. This behavior allows scripts to track conditions during bars.

The following example script uses the secondsSince() function from the PineCoders’ time library. This function uses variables declared with varip to track the number of seconds that elapse within a realtime bar while a condition remains true. Our script waits for price to move a user-defined number of ticks from the open, and then starts a timer. When the appropriate number of seconds elapses, it triggers an alert. A table displays these conditions in real time.

Note that:

• The secondsSince() function from the PineCoders’ time library resets the timer if the supplied condition (in this case, the price condition) becomes false at any time.
• The secondsSince() function only works in real time, because it relies on intrabar updates, which are not present on historical bars. Therefore, it is possible for the timer to exceed a given specified time, especially on symbols with low liquidity, if a bar update does not occur around the time that the timer should finish.
• We include the option to reset the timer on every bar or not, for demonstration purposes. The price condition in this example script resets on each bar, but other implementations might use different conditions.

For more information on the secondsSince() function and the use of varip variables, consult the PineCoders’ Using varip variables publication.

How can I identify the nth occurrence of a weekday in the month?

The following example script colors the background of the nth occurence of a user-configurable weekday. This identification can be useful for scheduled events that occur on specific weekdays, such as certain options expiry days.

Note that:

• We use an enum input to specify the target weekday, and convert it to an integer using a switch structure.
• The custom function daysPerMonth() calculates the number of days in any given month, considering leap years.
• The weekdayOfMonth() function determines the timestamp for the nth occurrence of a selected weekday within a specific month. This function first calculates the start time of the month and assesses the total number of days it contains. The function accounts for the unique characteristic of futures symbols, which begin trading on Sunday night, potentially causing a one-day discrepancy in the calculation.
• We plot the time of the bar close and of the occurence to the Data Window.

How can I count down the remaining time in a bar?

Users can display a countdown on the price scale of the chart that shows the time remaining in each bar, by enabling the “Countdown to bar close” option in the “Scales and lines” section of the chart “Settings” menu. Our example script below displays a similar countdown timer. This script functions on intraday and “1D” timeframes only. For timeframes longer than “1D”, more complex logic is necessary. The script throws a runtime error if the chart timefrmae is greater than one day.

We subtract timenow from time_close to calculate the time remaining in the current bar, and then display the result in a table.

Because Pine scripts run only when there is a chart update, countdown timers do not usually update every second. The script refreshes more often on symbols with higher liquidity.

Note that:

• We use the str.format_time() function to present the timestamp in a format similar to the price scale countdown timer. The function uses a conditional format so that we display hours only if the time remaining is one hour or greater.
• The built-in bar countdown uses a background the same color as the current candle. Pine scripts do not have access to the chart candle color settings, but if the user sets the correct colors in the script settings, our countdown displays in the same way.
• We use a custom function to analyze the luminance of the background colors and decide whether black or white text has the better contrast.

How can I get the week of the month?

Counting the week of the month in which the current bar occurs is not always straightforward. Some symbols trade overnight, so the time of the bar open is technically the previous day to the bar close, and sometimes the previous week. Because weekofyear, month, and similar variables use time (the time of the bar open) in their calculations, they can give unexpected results. The following example script, which uses these variables, gives unexpected results on some symbols such as US futures charts. For example, it increments the number of weeks on a Tuesday if the first trading day of the month is a Monday.

The following amended script version uses the functions weekofyear() and month() instead of the equivalent variables, and evaluates the time_tradingday variable, which, unlike time, returns the beginning time of the trading day that the bar belongs to. Using this variable, and fixing the timezone to “UTC”, avoids problems with sessions that span days.

While the preceding examples are useful for understanding the difference between time and time_tradingday, the simplest solution is to use the timeframe.change() function, which detects changes in a given timeframe. We can rewrite the boolean conditions in our example script as follows:

Note that:

• All versions of the script reset the number of weeks at the beginning of the month, then increment the count each new week.
• These scripts do not plot anything on timeframes of one month or greater.
• In Pine V5 and below, scripts can assign values of type “float” and “int” to a boolean variable. A value of zero is equivalent to false, and any other value to true. In later versions of Pine, scripts can assign only boolean values to boolean variables. So in V5, this code works: bool isNewMonth = ta.change(month) but in later versions this equivalent code is needed: bool isNewMonth = ta.change(month) != 0.