# Timeframes and sessions (/vela-pro/data/symbols/sessions)



Each market data request specifies a single timeframe and trading session, and your provider serves as the source of truth for when each market is open. This page covers the timeframe strings passed to `getBars` and `subscribe`, regular and extended session filtering, the `getCalendar` contract, display time zones, and the session presets shared across Vela Pro profile features.

## Timeframes [#timeframes]

Vela's open-source core forwards the chart's timeframe string directly to `getBars` and `subscribe` without aggregating one timeframe from another. Each timeframe is requested and cached as an independent series. When your upstream API does not natively serve a requested interval, aggregate finer bars inside your provider.

| Source                                             | String passed to your provider                                                                                                             |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Top bar timeframe presets                          | Configured preset string (`'1'`, `'5'`, `'15'`, `'30'`, `'60'`, `'240'`, `'D'`, `'W'`, and `'M'` by default, replaceable via `timeframes`) |
| Keyboard timeframe entry (`45`, `3h`, `2D`, `30S`) | Intraday intervals normalized to minutes (`'45'`, `'180'`, `'2880'`), with seconds retaining `'S'` (`'30S'`)                               |
| Constructor `timeframe` option                     | Exact string configured in options                                                                                                         |

Numeric strings without a unit represent minutes. Uppercase `'D'`, `'W'`, and `'M'` represent days, weeks, and months (optionally preceded by a multiplier such as `'2W'` or `'3M'`), while `'S'` represents seconds. Lowercase aliases (`'15m'`, `'4h'`, `'1d'`, `'1w'`) are also accepted through options, which makes letter case significant between `'M'` (month) and `'m'` (minute). Always normalize incoming timeframe strings before mapping them to upstream API intervals, because many external APIs treat `M` as minutes.

Several Vela Pro features also request auxiliary timeframes directly from your provider:

* **TPO** requests candles at its configured block interval (`'5'`, `'15'`, `'30'`, `'60'`, or `'240'`) regardless of the chart's active timeframe, issuing one `[from, to]` request per session without `limit`.
* **Default quotes** in the watchlist and symbol search request recent `'D'` bars and subscribe to `'D'` updates.
* **Bar replay** (when configured with the replay resolution control) requests the selected lower timeframe across `[from, to]` windows without `limit`.

### Rejecting unsupported timeframes [#rejecting-unsupported-timeframes]

Returning an empty array `[]` indicates that no bars exist within the requested time window. When an instrument never supports a requested timeframe granularity (for example, minute intervals on a monthly economic series), throw `DataUnavailableError` instead.

```ts
import { DataUnavailableError, type DataProvider } from '@luxalgo/vela';

declare const fetchCandles: DataProvider['getBars']; // upstream bar request

export const getBars: DataProvider['getBars'] = async (ticker, timeframe, range) => {
    // Monthly macroeconomic series with no intraday data.
    if (ticker === 'CPI' && /^\d+$/.test(timeframe)) {
        throw new DataUnavailableError({ reason: 'timeframe', finest: '1M', default: '1M' });
    }
    return fetchCandles(ticker, timeframe, range);
};
```

Throwing `DataUnavailableError` stops loading and polling for that series and emits `data:unavailable`. The workspace switches the chart to `default` (or `finest` when `default` is omitted) while preserving the user's chosen timeframe for the next symbol that supports it. Format `finest` and `default` using uppercase unit suffixes (`'60'`, `'1D'`, `'W'`, `'1M'`), matching the `timeframes` field in [Symbol metadata](/vela-pro/data/symbols/symbology#symbol-metadata).

## Regular and extended sessions [#regular-and-extended-sessions]

A chart displays either the `'regular'` session (default) or the `'extended'` session, which includes pre-market and post-market trading. Set the initial session with the `session` workspace option; users can switch sessions from the bottom bar.

Every bar request includes the active session via `range.session` in `getBars` and `opts.session` (the fourth argument) in `subscribe`. Regular and extended bars are cached as separate series. Providers whose markets trade continuously can ignore this parameter.

Session controls, pre/post-market background shading, and calendar queries activate when `getSymbolInfo` declares session hours:

```ts
import type { DataProvider } from '@luxalgo/vela';

const API = 'https://api.example.com';

export const hours: Pick<DataProvider, 'getSymbolInfo' | 'getCalendar'> = {
    async getSymbolInfo(ticker) {
        // Regular and extended hours formatted as HHMM-HHMM in the exchange time zone.
        return { ticker, timezone: 'America/New_York', session: '0930-1600', session_extended: '0400-2000' };
    },
    async getCalendar(ticker, range) {
        const query = new URLSearchParams({ symbol: ticker, from: String(range.from), to: String(range.to), session: range.session ?? 'regular' });
        const windows = (await (await fetch(`${API}/calendar?${query}`)).json()) as Array<[number, number]>;
        return windows.sort((a, b) => a[0] - b[0]);
    },
};
```

`session` specifies regular trading hours, and `session_extended` specifies the full trading day surrounding them. An extended span whose end time precedes its start time (`'1700-1600'`) represents an overnight trading day running from evening to evening. The chart computes pre-market and post-market background shading directly from these two strings.

## Market calendar [#market-calendar]

`getCalendar(ticker, range)` returns the intervals during which the market is open between `range.from` and `range.to` as ascending `[open, close)` pairs in epoch milliseconds, with market holidays, early closes, and daylight saving time already applied. `range.session` selects either `'regular'` windows (default) or `'extended'` windows. Because the core contains no built-in holiday rules, `getCalendar` is the sole source of schedule exceptions.

On symbols whose `getSymbolInfo` metadata declares a `session`, three features read `getCalendar`:

* **Market status badge** in the chart status line (`Market Open`, `Pre-Market`, `Post-Market`, `Extended Hours`, `Market Closed`, or `Market Holiday`). It queries both regular and extended windows around the current time and updates automatically at each session boundary.
* **Session-anchored profiles** (TPO, Session Volume Profile, and Session Volume Tails). Daily profiles cover the calendar's open window for each trading day, while weekly and monthly profiles group those daily windows.
* **Live footprint filtering** on regular-hours charts. Vela Pro drops incoming live footprint slices that fall outside the regular calendar windows.

### Continuous markets [#continuous-markets]

For markets that trade 24/7, omit `getCalendar` and return `session: '24x7'` (or omit `session`) from `getSymbolInfo`. The market status badge stays on `Market Open`, the bottom bar hides the session toggle, and session profiles align to UTC boundaries (`00:00 UTC` for days, Monday for weeks, and the first of the month for months).

## Display time zone [#display-time-zone]

The workspace `timezone` option sets the display time zone for the time axis and crosshair readout. Pass an IANA time zone string (`'Etc/UTC'` by default) or `'exchange'`, which renders each chart in the `timezone` declared by its symbol's metadata. Call `workspace.setTimezone(zone)` to update it programmatically, or let users switch zones from the bottom bar.

Time zone conversion applies to intraday bars only. Daily, weekly, and monthly bars represent calendar trading dates; stamp their `time` at `00:00:00 UTC` of the trading date so they display that date consistently across every time zone.

## Session presets [#session-presets]

The TPO chart type, overlay TPO indicator, Session Volume Profile, and Session Volume Tails share a common session model. Profiles anchor to **Day**, **Week**, or **Month** periods, and **Day** profiles can be narrowed to a trading-hours preset:

| Trading hours preset                      | Window definition                                                                                   |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Full day                                  | Calendar windows matching the session currently shown on the chart                                  |
| Regular hours (RTH), Extended hours (ETH) | Regular or extended calendar windows regardless of the chart's session toggle                       |
| Pre-market, Market, Post-market           | `09:00`-`13:30`, `13:30`-`20:00`, and `20:00`-`24:00` UTC                                           |
| London, New York, Asia                    | `08:00`-`16:30`, `13:00`-`22:00`, and `00:00`-`09:00` UTC                                           |
| Custom                                    | Start and end times formatted as `HHMM` in UTC (an end time earlier than start wraps past midnight) |

The first two rows follow your provider's `getCalendar` windows, whereas the named regional and sub-session presets use fixed UTC clock times. When a symbol has no calendar, `Full day` and `Extended hours` use `00:00`-`24:00` UTC and `Regular hours` uses `13:30`-`20:00` UTC.

Two preset labels differ between the TPO chart type and the indicators (`Full day` is labeled `All day` in the indicators, and `Market` is labeled `Market (US)`). See [TPO](/vela-pro/charts/chart-types/tpo) and [Built-in indicators](/vela-pro/indicators/included) for setting details.

## Related [#related]

* [Custom data providers](/vela-pro/data/custom-source)
* [Symbology](/vela-pro/data/symbols/symbology)
* [Adding a data provider](/vela/contributing/adding-a-data-provider#the-contract) in the core documentation
