Skip to content

History K-Line ​

GET /api/v1.0/quote/{symbol}/history-kline

Get historical K-line data for a specified time range, with pagination toward earlier data.

Token pagination: when history quota protection is enabled, send pagination.next_page_token as page_token. Tokens expire after 15 minutes and bind the current user, symbol and effective start/ktype/autype/num/extended_time/pred_side values; keep these unchanged. end/next_time may be omitted; an explicit next_time must match the token. Only history rules designated for first-page requests exempt valid continuation pages; other rate limits still apply. Without a token, provide end or next_time; next_time alone counts as a first-page request. When history quota protection is disabled, no token is returned and page_token yields -8 unsupported; restart using end or next_time.

Parameters ​

NameTypeInRequiredDescription
symbolstringpathyesStock symbol (path param), e.g. US.FUTU / HK.00700 Max length 128; Pattern ^[A-Z0-9_]+\.[A-Za-z0-9_.\-]+$
startstringquerynoStart date yyyy-MM-dd (inclusive). If omitted, the server walks backward from end by num bars. e.g. 2026-05-20 Max length 10; Pattern ^$|^\d{4}-\d{2}-\d{2}$
endstringquerynoEnd date YYYY-MM-DD in the instrument market timezone. For minute bars, the cutoff is 00:00 on this date and excludes its minute data; set end to the following date for a single-day query. Daily bars include the end date. Without a valid page_token, provide end or next_time. May be omitted for token continuation. Max length 10; Default ""; Pattern ^$|^\d{4}-\d{2}-\d{2}$
next_timeintquerynoPaging-backward cursor (millisecond timestamp); pass back the data.next_time from the previous page. When set, it is used as the next page's end (seconds, half-open, excludes the earliest item of the previous page) and takes precedence over end. 0 means unused. e.g. 1779163200000 Default 0
ktypeintquerynoK-line type. Second K (via kline_type_v2): 101=1s / 105=5s / 110=10s / 115=15s / 130=30s / 145=45s. Minute and above: 1=1-min / 2=day (default) / 3=week / 4=month / 5=year / 6=5-min / 7=15-min / 8=30-min / 9=60-min / 10=3-min / 11=quarter / 14=120-min / 15=240-min / 26=10-min / 29=180-min. Option second K: 110/115/130 only Default 2
autypeintquerynoAdjustment type. 0=None / 1=Forward (default) / 2=Backward Default 1; Values 0, 1, 2
numintquerynoNumber of K-line bars to return, default 370, max 370 ≥ 1; ≤ 370; Default 370
extended_timeintquerynoPre/after-hours flag. 0=default (excluded) / 1=include pre/after-hours (US intraday K-line) / 2=include overnight session (US) Default 0; Values 0, 1, 2
pred_sideintquerynoEvent contracts only. 0=use symbol as-is (default); 1=resolve YES sub-contract; 2=resolve NO. A.YES/.NO suffix still follows pred_side (.YES + pred_side=2 looks up NO). Ignored for other instruments Default 0; Values 0, 1, 2
page_tokenstringquerynopagination.next_page_token from the previous page; valid for 15 minutes. Omit or use an empty string to start a new query. Max length 48; Pattern ^$|^[0-9a-f]{48}$

Request Example ​

To retrieve QQQ 1-minute bars for 2026-11-09, use start=2026-11-09&end=2026-11-10. Setting both dates to 2026-11-09 returns an empty minute-bar list. Use ktype=6 for 5-minute bars. Daily bars (ktype=2) include the end date, so a single-day query may use the same start and end date.

bash
curl 'https://webapi.futunn.com/api/v1.0/quote/US.QQQ/history-kline?start=2026-11-09&end=2026-11-10&ktype=1&autype=1&num=370&extended_time=0' | jq

Response Fields ​

NameTypeDescription
dataobject
data.kline_listobject[]
data.kline_list[].time_keyintK-line time, millisecond timestamp, e.g. 1779249600000
data.kline_list[].dateintK-line date in YYYYMMDD (intraday K = the trading day it belongs to; daily and above = local date of the timestamp), e.g. 20260523
data.kline_list[].time_zoneintTime-zone offset in minutes from UTC, used to convert time_key into the local time of the symbol's market, e.g. 480 (HK) / -300 (US DST)
data.kline_list[].opennumberOpen price, e.g. 124.12
data.kline_list[].closenumberClose price, e.g. 124.72
data.kline_list[].highnumberHighest price, e.g. 127.45
data.kline_list[].lownumberLowest price, e.g. 122.7
data.kline_list[].volumeintVolume (shares), e.g. 2960896
data.kline_list[].turnovernumberTurnover, e.g. 370529897
data.kline_list[].last_closenumberPrevious close price, e.g. 124.5
data.kline_list[].pe_rationumberPrice-to-earnings ratio (PE), e.g. 17.728
data.kline_list[].turnover_ratenumberTurnover rate (percentage), e.g. 0.49348
data.kline_list[].change_ratenumberChange rate (percentage, relative to previous close), e.g. 0.17670682730923695
data.kline_list[].open_interestintOpen interest (returned only for futures / options; 0 or omitted for other categories), e.g. 12345
data.kline_list[].settle_pricenumberSettlement price: only meaningful for futures / options on daily K and above. For other categories (equities / ETFs / indices, etc.) the server echoes the close price into this field; callers must ignore it for non-derivative symbols. e.g. 124.5
data.kline_list[].implied_volatilitynumberImplied volatility (percentage, returned only for options; 0 or omitted for other categories), e.g. 12.345
data.kline_list[].namestringStock English name
data.kline_list[].sc_namestringStock Simplified Chinese name
data.kline_list[].tc_namestringStock Traditional Chinese name
data.next_timeintNext-page end cursor (millisecond timestamp, half-open, excludes the earliest item of this page). Only present when has_more=true (older data exists beyond the range); pass it back via the next_time param to page toward earlier data. e.g. 1779163199999
data.volume_precisionintVolume precision n. kline_list[].volume is magnified by 10^n; divide by 10^n to recover the real volume. Usually >0 only for niche categories (event contracts, crypto); equities / ETFs / futures / options are typically 0, e.g. 0
paginationobject
pagination.has_morebool
pagination.next_page_tokenstringNext-page token, returned only when history quota protection is enabled, this page is nonempty and has_more=true. Return as page_token within 15 minutes.

Supported Markets ​

  • Code must use a supported market prefix from the registered market prefixes; otherwise returns invalid_symbol (e.g. HK / US / SH / SZ / BJ / SG / CA / AU / FX / JP / KR / CC / FT, etc.).
  • Supported categories: Stocks / ETFs / Indices / Futures / Options / Crypto; unsupported categories like preferred shares / SPACs / convertible bonds / CBBCs return an empty kline_list.
  • Market prefixes not in the supported enum (e.g. UK / IT): returns ret_code=-8 unsupported.

Error Codes ​

ret_codeerror.codeTrigger ConditionRecommended Action
0—Success; when valid but no data, kline_list is an empty array—
-3invalid_parameterWithout a valid page_token, both end and next_time are missing / type error / invalid enum (ktype out of range) / date format mismatchCorrect parameters and retry
-7invalid_symbolsymbol format is valid but no matching security was found (e.g. HK.99999999)Use the search API to confirm symbol validity
-8unsupportedMarket prefix not in supported range (e.g. UK.HSBA / IT.STM)Confirm whether the market prefix is supported

| -3 | invalid_page_token | Token expired, invalid or query changed | Restart with end or next_time | | -11 | rate_limited / history_quota_busy | Rate limit or pending target | Back off for Retry-After seconds | | -12 | history_quota_exceeded | New target quota exhausted | Wait for quota release | | -13 | quota_unavailable | Quota service unavailable | Retry later |

Response Example ​

json
{
  "ret_code": 0,
  "ret_msg": "success",
  "data": {
    "kline_list": [
      {
        "change_rate": 0.17670682730923695,
        "close": 124.72,
        "high": 127.45,
        "last_close": 124.5,
        "low": 122.7,
        "name": "富途控股",
        "open": 124.12,
        "pe_ratio": 17.728,
        "time_key": 1779249600000,
        "turnover": 370529897,
        "turnover_rate": 0.49348,
        "volume": 2960896
      },
      {
        "change_rate": -0.689544579858884,
        "close": 123.86,
        "high": 125.45,
        "last_close": 124.72,
        "low": 122.1,
        "name": "富途控股",
        "open": 122.7,
        "pe_ratio": 17.606,
        "time_key": 1779336000000,
        "turnover": 271859605,
        "turnover_rate": 0.36631,
        "volume": 2197832
      }
    ]
  },
  "pagination": {
    "has_more": false
  }
}

Quota and continuation ​

The first successful nonempty result consumes one historical slot, released after 7×24 hours by default; rereads do not extend expiry. Failed or empty results do not add usage. Periods, adjustments and pages share a target slot; options are grouped by market, underlying and expiry in an independent pool. See market data permissions and quotas.

When pagination.has_more=true, prefer returning pagination.next_page_token unchanged; if absent, return data.next_time. Stop when has_more=false. Do not parse or generate tokens.