History K-Line
GET/api/v1.0/quote/{symbol}/history-klineGet 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
| Name | Type | In | Required | Description |
|---|---|---|---|---|
symbol | string | path | yes | Stock symbol (path param), e.g. US.FUTU / HK.00700 Max length 128; Pattern ^[A-Z0-9_]+\.[A-Za-z0-9_.\-]+$ |
start | string | query | no | Start 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}$ |
end | string | query | no | End 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_time | int | query | no | Paging-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 |
ktype | int | query | no | K-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 |
autype | int | query | no | Adjustment type. 0=None / 1=Forward (default) / 2=Backward Default 1; Values 0, 1, 2 |
num | int | query | no | Number of K-line bars to return, default 370, max 370 ≥ 1; ≤ 370; Default 370 |
extended_time | int | query | no | Pre/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_side | int | query | no | Event 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_token | string | query | no | pagination.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.
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' | jqResponse Fields
| Name | Type | Description |
|---|---|---|
data | object | |
data.kline_list | object[] | |
data.kline_list[].time_key | int | K-line time, millisecond timestamp, e.g. 1779249600000 |
data.kline_list[].date | int | K-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_zone | int | Time-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[].open | number | Open price, e.g. 124.12 |
data.kline_list[].close | number | Close price, e.g. 124.72 |
data.kline_list[].high | number | Highest price, e.g. 127.45 |
data.kline_list[].low | number | Lowest price, e.g. 122.7 |
data.kline_list[].volume | int | Volume (shares), e.g. 2960896 |
data.kline_list[].turnover | number | Turnover, e.g. 370529897 |
data.kline_list[].last_close | number | Previous close price, e.g. 124.5 |
data.kline_list[].pe_ratio | number | Price-to-earnings ratio (PE), e.g. 17.728 |
data.kline_list[].turnover_rate | number | Turnover rate (percentage), e.g. 0.49348 |
data.kline_list[].change_rate | number | Change rate (percentage, relative to previous close), e.g. 0.17670682730923695 |
data.kline_list[].open_interest | int | Open interest (returned only for futures / options; 0 or omitted for other categories), e.g. 12345 |
data.kline_list[].settle_price | number | Settlement 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_volatility | number | Implied volatility (percentage, returned only for options; 0 or omitted for other categories), e.g. 12.345 |
data.kline_list[].name | string | Stock English name |
data.kline_list[].sc_name | string | Stock Simplified Chinese name |
data.kline_list[].tc_name | string | Stock Traditional Chinese name |
data.next_time | int | Next-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_precision | int | Volume 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 |
pagination | object | |
pagination.has_more | bool | |
pagination.next_page_token | string | Next-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_code | error.code | Trigger Condition | Recommended Action |
|---|---|---|---|
| 0 | — | Success; when valid but no data, kline_list is an empty array | — |
| -3 | invalid_parameter | Without a valid page_token, both end and next_time are missing / type error / invalid enum (ktype out of range) / date format mismatch | Correct parameters and retry |
| -7 | invalid_symbol | symbol format is valid but no matching security was found (e.g. HK.99999999) | Use the search API to confirm symbol validity |
| -8 | unsupported | Market 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
{
"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.