Pine Script timeframe_bars_back Parameter Explained

Pine Script's time() and time_close() functions have always been essential for working with timestamps in TradingView indicators and strategies¹. The October 2025 update added a new parameter called timeframe_bars_back that unlocks a capability that was previously difficult to achieve: offsetting timestamps directly on a separate higher timeframe rather than on the chart's own timeframe².

This guide explains what timeframe_bars_back does, how it differs from the existing bars_back parameter, and how to combine both parameters for precise cross-timeframe timestamp calculations.

What timeframe_bars_back Does

Before October 2025, the time() and time_close() functions already supported a bars_back parameter that let you retrieve the opening or closing timestamp of a bar that is a certain number of chart bars back from the current bar³. The key word there is "chart bars." The offset was always relative to the script's main timeframe.

The new timeframe_bars_back parameter works differently. Instead of offsetting on the chart's timeframe, it offsets on the separate timeframe specified by the function's timeframe argument³. If you call time("1M", timeframe_bars_back = 3), the function returns the opening timestamp of the monthly bar that is three monthly bars back from the current monthly bar, regardless of what chart timeframe you are viewing.

This distinction matters because monthly bars, weekly bars, and daily bars do not align neatly with intraday chart bars. A single monthly bar might contain hundreds or thousands of 5-minute bars. Offsetting by three monthly bars on the monthly timeframe is a fundamentally different operation than offsetting by three chart bars and then finding the corresponding monthly bar.

bars_back vs timeframe_bars_back

Understanding the difference between these two parameters is critical. They both perform offsets, but on different timeframes.

bars_back: Offsets on the script's main timeframe (the chart timeframe)³. If you are on a 5-minute chart and set bars_back = 10, the function first moves 10 five-minute bars back from the current bar. Then it finds the opening or closing time of the specified higher timeframe bar that contains that offset bar.

timeframe_bars_back: Offsets on the timeframe specified in the function call³. If you call time("1M", timeframe_bars_back = 3), the function finds the monthly bar that contains the current chart bar and then moves three monthly bars back from that bar. The offset operates entirely in the monthly timeframe's bar sequence.

The direction of the offset also differs in one important way. Both parameters treat positive values as backward offsets (looking into the past). However, timeframe_bars_back also supports negative values, which calculate the expected timestamp of a future bar on the specified timeframe². The bars_back parameter is limited to non-negative values³.

Quick Comparison

• bars_back = 10 on a 5-minute chart moves 10 five-minute bars back, then finds the corresponding higher timeframe bar
• timeframe_bars_back = 3 moves 3 bars back on the specified timeframe directly
• bars_back uses chart timeframe units; timeframe_bars_back uses the specified timeframe units
• timeframe_bars_back supports negative values for future bar timestamps; bars_back does not³

Combining Both Parameters

The real power of this update appears when you use both parameters in a single function call. When a call to time() or time_close() includes arguments for both bars_back and timeframe_bars_back, the function applies them in a specific order².

First, it determines the timestamp corresponding to the bars_back offset on the chart timeframe. This gives a reference point that is some number of chart bars in the past. Second, it applies the timeframe_bars_back offset to that reference point on the specified higher timeframe². The result is the final timestamp.

For example, suppose you are on a 5-minute chart and call time("1M", bars_back = 10, timeframe_bars_back = 3). The function first finds the monthly bar that contains the chart bar from 10 five-minute bars ago. Then it moves three monthly bars back from that monthly bar and returns its opening timestamp.

This two-step process lets you answer questions like: "Starting from a specific historical chart bar, what was the opening time of the monthly bar that was three months earlier?" Previously, you would have needed complex custom logic to calculate this.

Code Example

The following example from the Pine Script release notes demonstrates how both parameters work together². It shows the difference between a simple monthly timestamp, a chart-offset monthly timestamp, and a combined chart-plus-monthly offset timestamp.

//@version=6
indicator("`bars_back` and `timeframe_bars_back` demo")

//@variable The number of bars back on the script's main timeframe (chart timeframe).
int barsBackInput = input.int(10, "Chart bar offset")
//@variable The number of bars back on the "1M" timeframe.
int tfBarsBackInput = input.int(3, "'1M' bar offset")

//@variable The opening UNIX timestamp of the current "1M" bar.
int monthTime = time("1M")
//@variable The opening time of the "1M" bar that contains the bar from `barsBackInput` bars back on the main timeframe.
int offsetTime1 = time("1M", bars_back = barsBackInput)
//@variable The "1M" opening time that is `tfBarsBackInput` monthly bars back, relative to the "1M" bar that opens
//          at `offsetTime1`. This call first determines the "1M" bar time corresponding to `barsBackInput` bars back
//          on the main timeframe, then calculates the "1M" opening time that is `tfBarsBackInput` monthly bars back
//          relative to that time.
int offsetTime2 = time("1M", bars_back = barsBackInput, timeframe_bars_back = tfBarsBackInput)

// Plot the values for visual comparison.
plot(monthTime, "Current month open", color.blue)
plot(offsetTime1, "Chart-offset month open", color.orange)
plot(offsetTime2, "Chart + TF offset month open", color.green)

In this example, the three plots show three different timestamps. The blue line shows the current monthly bar's opening time. The orange line shows the monthly bar opening time corresponding to a chart bar offset of 10 bars back. The green line adds an additional three-month offset on top of the chart bar offset, reaching further into the past.

Finding Previous Period Starts

One of the most practical uses for timeframe_bars_back is finding the start of the previous week, month, or quarter from any bar on the chart. Before this parameter existed, the standard approach was to detect when a higher timeframe bar changed using ta.change(time("1M")) and then store timestamps in variables. That approach worked but was verbose and error-prone.

With timeframe_bars_back, you can retrieve the start of the previous month in a single line:

//@version=6
indicator("Previous month start", overlay = true)

//@variable The opening timestamp of the monthly bar before the current one.
int prevMonthStart = time("1M", timeframe_bars_back = 1)

// Draw a vertical line at the start of the previous month on the last confirmed bar.
if barstate.islastconfirmedhistory
    line.new(prevMonthStart, low, prevMonthStart, high, xloc = xloc.bar_time,
         color = color.red, width = 2, style = line.style_dashed)

This pattern works for any timeframe string. Use "1W" for the previous week, "3M" for the previous quarter, or "1D" for the previous day. The timestamp calculation handles varying month lengths, weekends, and holidays automatically because TradingView resolves the offset based on actual bar data.

Retrieving Weekly Close Times

The time_close() function also supports timeframe_bars_back³. You can retrieve the closing timestamp of a previous higher timeframe bar just as easily:

//@version=6
indicator("Previous week close time", overlay = true)

//@variable The closing timestamp of the weekly bar before the current one.
int prevWeekClose = time_close("1W", timeframe_bars_back = 1)

// Display the formatted close time on the last bar.
if barstate.islast
    label.new(bar_index, high, str.format("Prev week closed: {0,date,yyyy-MM-dd HH:mm}", prevWeekClose),
         style = label.style_label_down, color = color.teal, textcolor = color.white)

Future Timestamp Projection

Negative values for timeframe_bars_back calculate the expected timestamp of a future bar on the specified timeframe³. If you call time("1W", timeframe_bars_back = -2), the function returns the expected opening timestamp of the weekly bar two weeks ahead of the current weekly bar.

This is useful for projecting support and resistance levels, drawing forward-looking zones on the chart, or planning trade management around known future time boundaries.

//@version=6
indicator("Future month projection", overlay = true)

//@variable The expected opening timestamp of the next monthly bar.
int nextMonthOpen = time("1M", timeframe_bars_back = -1)
//@variable The expected opening timestamp of the monthly bar two months ahead.
int twoMonthsAhead = time("1M", timeframe_bars_back = -2)

// Display future month boundaries.
if barstate.islast
    line.new(nextMonthOpen, low, nextMonthOpen, high, xloc = xloc.bar_time,
         color = color.green, width = 2, style = line.style_dashed)
    line.new(twoMonthsAhead, low, twoMonthsAhead, high, xloc = xloc.bar_time,
         color = color.orange, width = 2, style = line.style_dashed)

Note that future timestamp projection works reliably on time-based charts where bars open and close at predictable times. On tick charts and non-standard charts like Renko or Kagi, the closing times of future bars are unpredictable, so the time() function with a negative offset may return na on those chart types³.

Key Limitations

There are a few constraints to keep in mind when using timeframe_bars_back.

• The timeframe parameter must specify a valid timeframe string such as "1D", "1W", or "1M" for the timeframe_bars_back offset to apply³
• Negative timeframe_bars_back values may return na on non-time-based charts such as tick, Renko, Kagi, and point and figure charts³
• The bars_back parameter is applied first and timeframe_bars_back second when both are specified, so the order of operations is fixed²
• The function returns na if the calculated offset references a bar that does not exist in the available data history³

Automate Your Strategies

Accurate timestamp calculations are essential for building reliable multi-timeframe strategies. Once you have verified your time-based logic using timeframe_bars_back, you can connect your TradingView strategies to a broker through TradersPost⁴. Set up webhook alerts in TradingView and let TradersPost route orders to your brokerage account automatically.

Whether you are aligning entries with monthly boundaries or managing positions around weekly closes, automating the execution ensures your strategy acts on the exact signals your Pine Script code generates.

Visit TradersPost to connect your TradingView strategies to live and paper trading accounts across stocks, options, futures, and crypto.

References

¹ Pine Script User Manual
² Pine Script Release Notes
³ Pine Script v6 Language Reference
⁴ TradersPost - Automated Trading Platform