Stock Screen
POST/api/v1.0/quote/stock-screenConditional stock screening: combine N filter conditions to filter, sort, and paginate across the entire market, returning multiple columns for each matched security based on specified retrieval factors. For warrant screening use warrant-screen; for option screening use option-screen.
Parameters
| Name | Type | In | Required | Description |
|---|---|---|---|---|
screen_queries | object[] | body | yes | Filter condition array. Each element is a "1-of-11" query object -- simple_field_query (market/exchange/index/northbound sector enum field IN list) / plate_query (plate filter) / simple_property_query (quote/valuation factor range) / cumulative_property_query (cumulative quote range, requires period) / financial_property_query (financial factor range, requires fiscal period) / indicator_positional_query (technical indicator positional relationship) / indicator_pattern_query (technical pattern) / featured_property_query (featured factor) / broker_holdings_query (broker holdings, HK only) / kline_shape_query (K-line pattern) / option_query (option indicator). Ranges use lower={value, includes} / upper={value, includes}, where value is pre-multiplied by the field's multiplier. Min items 1; Max items 10000 |
retrieve_queries | object[] | body | no | Retrieval factor array. Each element is a "1-of-9" retrieve object -- basic_property / simple_property / cumulative_property / financial_property / featured_property / indicator_property / broker_property / kline_shape_property / option_property. Return order aligns exactly with retrieve_queries. Max items 10000 |
sort | object | body | no | Single-field sort (mutually exclusive with sorts; sorts takes priority). Structure: {direction, simple_property:{name}} (can also use cumulative_property / financial_property / featured_property). direction: 1=ASC, 2=DESC, 3=ASC by absolute value, 4=DESC by absolute value. |
sorts | object[] | body | no | Sort fields, in priority order. Max items 10000 |
next_key | string | body | no | Pagination cursor. Leave empty for the first page. Max length 1000; Pattern ^$|^(-?[0-9]+)?$ |
limit | int | body | no | Page size. ≤ 300; Default 200 |
watchlist_stock_ids | int[] | body | no | Watchlist stock IDs. Pass only when screening within the watchlist. Max items 10000 |
holding_stock_ids | int[] | body | no | Holding stock IDs. Pass only when screening within holdings. Max items 10000 |
user_stock_list_mode | int | body | no | Scope: 0 any, 1 watchlist only, 2 holdings only. Values 0, 1, 2 |
Request Example
bash
curl -X POST "https://webapi.futunn.com/api/v1.0/quote/stock-screen" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AccessToken>" \
-d '{"limit":3,"screen_queries":[{"simple_field_query":{"simple_field":1,"screen_value_list":[1]}}],"retrieve_queries":[{"simple_property":{"name":2201}},{"simple_property":{"name":2301}},{"simple_property":{"name":2303}}],"sort":{"direction":2,"simple_property":{"name":2301}}}' | jqResponse Fields
| Name | Type | Description |
|---|---|---|
data | object | |
data.items | object[] | |
data.items[].code | string | Stock symbol with market prefix, e.g. HK.00700 |
data.items[].name | string | Stock English name , e.g. TENCENT |
data.items[].sc_name | string | Stock Simplified Chinese name, e.g. 腾讯控股 |
data.items[].tc_name | string | Stock Traditional Chinese name, e.g. 騰訊控股 |
data.items[].results | object[] | Retrieve-factor results for this symbol corresponding to each retrieve_queries entry , containing basic_property_result / simple_property_result / financial_property_result, etc. res.ival is the raw integer value (including multiplier); result_type=2 means int. Multiplier rule: multiples (PE/PB/PS/PCF/volume ratio/BETA) x1e5; price/change amount x1000; market cap/turnover x1000; percentage factors (change rate/amplitude/turnover rate/dividend yield/all growth·margin·return·holding-ratio etc.) are ALWAYS x1e3 (returned value = percentage x 1000; divide by 1e3 to restore the percentage). e.g. [{simple_property_result:{property:{name:2201}, res:{ival:"505000", result_type:2}, value:"505000"}}] |
pagination | object | |
pagination.total | int | |
pagination.has_more | bool | |
pagination.next_key | string |
Scope & Limits
- Supported markets: HK (Hong Kong) / US (United States) / CN (A-shares) / SG (Singapore) / CA (Canada) / AU (Australia) / JA (Japan) / MY (Malaysia) / KR (Korea).
- Supported categories: Stocks / ETF / Index / REIT and other securities within screening scope; use
warrant-screenfor warrants,option-screenfor options. broker_holdings_query/kline_shape_queryonly available for HK market;option_queryrequires the security to have options.- Single page
limitmax 300;next_keyis an opaque cursor. - Valid but no-hit queries (overly strict filters, or unsupported markets) return
ret_code=0+data.items=[]+pagination.total=0. Empty results are a success, not an error.
Error Codes
| ret_code | error.code | Trigger Condition | Handling |
|---|---|---|---|
| -3 | invalid_parameter | Missing required screen_queries; limit > 300; invalid next_key; user_stock_list_mode value not in {0,1,2}; other field type errors. | Correct the request body and retry. |
| -5 | internal_error | Service error | Check query structure and property name / market value validity, then retry. |
| -6 | internal_error | Service error | Contact support for investigation. |
Response Example
json
{
"ret_code": 0,
"ret_msg": "success",
"data": {
"items": [
{
"code": "HK.05432",
"name": "...",
"sc_name": "...",
"tc_name": "...",
"results": []
},
{
"code": "HK.00700",
"name": "TENCENT",
"sc_name": "腾讯控股",
"tc_name": "騰訊控股",
"results": []
}
]
},
"pagination": {
"has_more": true,
"next_key": "3",
"total": 2938
}
}