Historical data and its limits

Historical bars

bars = await ib.reqHistoricalDataAsync(
    contract=contract,
    endDateTime="",          # now; or timezone-aware datetime/string
    durationStr="30 D",
    barSizeSetting="1 hour",
    whatToShow="TRADES",
    useRTH=True,
    formatDate=2,
    keepUpToDate=False,
    chartOptions=[],
    timeout=60,
)

Parameter	Exact role
endDateTime	End boundary. Empty means now. For keepUpToDate=True, it must be empty. Prefer UTC yyyyMMdd-HH:mm:ss or a timezone-aware datetime.
durationStr	Integer plus unit: seconds (S), days (D), weeks (W), months (M), years (Y). It is a lookback, not a requested row count.
barSizeSetting	One of IBKR's exact tokens such as 1 sec, 5 secs, 1 min, 1 hour, 1 day.
whatToShow	Data series such as TRADES, MIDPOINT, BID, ASK, BID_ASK, ADJUSTED_LAST, volatility, fee rate, or SCHEDULE, subject to instrument support.
useRTH	If true, filter to regular trading hours as defined by IBKR for the instrument.
formatDate	1 returns formatted dates; 2 makes intraday bar dates timezone-aware UTC datetimes in ib_async. Daily bars remain date-like.
keepUpToDate	Keep the newest bar updated. Cancel with cancelHistoricalData(bars).
timeout	ib_async wait limit. On timeout it cancels and returns an empty bar list in this code path; inspect logs/errors.

Daily futures bars may use the settlement price, which can become available hours after the session close and can be revised. A daily session can cross calendar days; the bar date is the trading-session date chosen by IBKR.

Step sizes

IBKR expects only a few thousand bars per request. Official examples:

Duration	Allowed bar-size range
60 S	1 sec through 1 min
120 S	1 sec through 2 mins
1800 S	1 sec through 30 mins
3600 S	5 secs through 1 hour
14400 S	10 secs through 3 hours
28800 S	30 secs through 8 hours
1 D	1 min through 1 day
2 D	2 mins through 1 day
1 W	3 mins through 1 week
1 M	30 mins through 1 month
1 Y	1 day through 1 month

For large downloads, page backward from the oldest returned timestamp with overlap, deduplicate by (contract, whatToShow, bar size, timestamp), and rate-limit centrally.

Pacing

For bars of 30 seconds or less, avoid identical requests within 15 seconds, six or more requests for the same contract/exchange/tick type within two seconds, and more than 60 requests in ten minutes. BID_ASK counts twice. No more than 50 historical requests may be open simultaneously; materially fewer is safer. IBKR has removed some hard limits for bars of one minute and larger but applies soft throttling and may disconnect abusive clients.

Unavailable history

IBKR documents these important exclusions:

• bars of 30 seconds or less older than six months;
• expired futures more than two years past expiration;
• expired options, futures options, warrants, and structured products;
• EOD data for options, FOPs, warrants, and structured products;
• expired futures spreads, delisted instruments, and often pre-migration data after an exchange change;
• native combo history (combo charts are derived from legs);
• chart studies/indicators, except supported raw fields such as VWAP.

Historical trade data is filtered differently from live data, so volume and VWAP can differ. If a period is absent from the equivalent TWS chart it will normally be absent from the API.

Historical ticks

reqHistoricalTicksAsync accepts exactly one of startDateTime or endDateTime, a maximum tick count (officially up to 1000 per request), whatToShow of TRADES, BID_ASK, or MIDPOINT, useRth, and ignoreSize. A request can return more than the nominal count to complete a second. Page with overlap and deduplicate using timestamp plus price/size/exchange/special conditions as appropriate.

Head timestamp and schedule

reqHeadTimeStampAsync finds the earliest available timestamp for a contract/data type; it does not promise continuous coverage after that point. reqHistoricalScheduleAsync returns sessions with start/end/timezone and is preferable to inventing exchange hours.

Official references: historical bars, historical limitations, and historical time and sales.