Historical Prices

Use historical prices when you need chart candles, returns, technical indicators, backtests, or time-series views.

Endpoint And SDK Calls

curl "https://api.yfin.dev/v1/history?symbol=AAPL&period=1mo&interval=1d" \
  -H "X-Yfin-Contact: you@example.com"

import yfin as yf

aapl = yf.Ticker("AAPL", contact="you@example.com")
history = aapl.history(period="1mo", interval="1d")

const history = await client.history("AAPL", {
  period: "1mo",
  interval: "1d",
});

Range And Interval

Use period or range for relative windows. Use start and end for exact date windows.

Parameter	Use when
period	Migrating yfinance-shaped code. Alias for range.
range	Calling the REST API directly with a relative window such as 5d, 1mo, 1y, or max.
start and end	You need an exact date window. Use YYYY-MM-DD or epoch seconds.
interval	You need daily, hourly, or intraday candles. Examples: 1d, 1h, 15m, 5m, 1m.
prepost	You want pre-market and post-market bars when available.
actions	You want dividend and split events included with the chart response.

Not every interval is valid for every range. Short intervals are usually available only for shorter windows. If a range/interval pair is not accepted, retry with a wider interval or shorter range.

Candle Fields

The history response contains chart metadata plus arrays for the requested series. Common fields include:

Field	Meaning
timestamp	Unix timestamps for each bar. Interpret with the exchange timezone in the chart metadata.
open, high, low, close	OHLC prices for each timestamp.
volume	Reported volume for each bar.
adjclose	Adjusted close series when returned for the symbol and interval.
events	Dividends, splits, or capital gains when requested and available.

Python Return Shape

The yfinance-compatible Python layer returns a pandas DataFrame for Ticker.history() and download(). Column names are shaped for yfinance-style code, while the low-level Client.history() returns the JSON envelope from the REST API.

Common Pitfalls

• Daily bars and intraday bars may use different timestamp conventions.
• Missing candles can represent market holidays, halted trading, unsupported intervals, or unavailable source data.
• Do not assume every symbol has an adjusted close series.
• For multi-symbol downloads, handle per-symbol gaps instead of requiring every symbol to share the same calendar.