GET/candles

Candles

Fetch raw OHLCV candle data for any supported market.

Returns an array of OHLCV (Open, High, Low, Close, Volume) candles ordered oldest to newest. Use this for charting, backtesting, or building custom indicators on raw price data.

Parameters

Name	Type	Required	Default	Description
`exchange`	string	Yes	—	Exchange identifier, e.g. `binance`, `bybit`. See Exchanges.
`symbol`	string	Yes	—	Trading pair, e.g. `BTCUSDT`.
`timeframe`	string	Yes	—	Candle interval: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`, `1w`.
`results`	integer	No	500	Number of candles to return. Use `max` to return all available candles.
`backtrack`	integer	No	0	Candles to skip from the most recent. Shifts the result window back in time.

Note: Use results=max to retrieve all available candle history for a symbol. Candles are returned oldest first — [0] is the oldest, the last element is the most recent.

Example

curl -G https://v2.taapi.io/candles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "exchange=binance" \
  --data-urlencode "symbol=BTCUSDT" \
  --data-urlencode "timeframe=1h" \
  --data-urlencode "results=3"

const res = await fetch(
  'https://v2.taapi.io/candles' +
  '?exchange=binance&symbol=BTCUSDT&timeframe=1h&results=3',
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
const candles = await res.json();

import requests

resp = requests.get(
    'https://v2.taapi.io/candles',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
        'exchange':  'binance',
        'symbol':    'BTCUSDT',
        'timeframe': '1h',
        'results':   3,
    }
)
candles = resp.json()

Response

Returns an array of candle objects, ordered oldest to newest. The last element in the array is the most recent candle.

200 OK — array of candles

[
  {
    "timestamp":      1708293600,
    "timestampHuman": "2024-02-19 00:00:00",
    "open":   51200.5,
    "high":   52100.0,
    "low":    50900.25,
    "close":  51850.75,
    "volume": 1234.56
  },
  {
    "timestamp":      1708297200,
    "timestampHuman": "2024-02-19 01:00:00",
    "open":   51850.75,
    "high":   52300.0,
    "low":    51600.0,
    "close":  52150.0,
    "volume": 987.32
  },
  {
    "timestamp":      1708300800,
    "timestampHuman": "2024-02-19 02:00:00",
    "open":   52150.0,
    "high":   52400.0,
    "low":    51900.5,
    "close":  52050.25,
    "volume": 1102.88
  }
]

Candle fields

Field	Type	Description
`timestamp`	integer	Unix timestamp (seconds) of the candle open.
`timestampHuman`	string	Human-readable UTC datetime: `YYYY-MM-DD HH:MM:SS`.
`open`	number	Opening price.
`high`	number	Highest price during the candle.
`low`	number	Lowest price during the candle.
`close`	number	Closing price.
`volume`	number	Trading volume during the candle.

Errors

Response

[{ "timestamp": 1708300800, "open": 52150.0, ... }]

Data is being fetched. Retry after 1–2 seconds.

Response

{ "pending": true, "key": "ta:binance:BTCUSDT:1h:..." }

Response

{ "error": "Missing required: exchange, symbol, timeframe" }

Response

{ "error": "Invalid or inactive token" }

Response

{ "error": "Too Many Requests", "retryAfter": 9 }

Bringing your own candles

To compute indicators on your own candle data, use Data Injection — POST /indicator/{indicator} or POST /bulk-candles. No exchange, symbol, or timeframe required.

See the full list of indicators, or start for free.