The market scanner allows you to quickly scan relevant markets and return the top contracts based on a defined set of instrument, parameter, location, and filtering criteria. The endpoint /iserver/scanner/params can be used to determine the available values.
Please be sure to authenticate first in order to resolve the below URLs.
For authentication details, visit https://interactivebrokers.github.io/cpwebapi/index.html#login
GET https://localhost:5000/v1/api/iserver/scanner/params
Response:
{
scan_type_list Array of objects
The available scanner parameters
Array () [
{
display_name string
The scanner parameter name
code string
The code for scanner parameter
instruments string
The list of available instruments that are supported
]
},
instrument_list Array of objects
The available types of instruments
Array () [
{
display_name string
The instrument name
type string
The asset class
filters string
The available data points that can be used to filter instruments
]
},
filter_list Array of objects
Defines the filters returned in instrument_list
Array () [
{
group string
The group of filter
display_name string
The filter name
code string
The code for filter name
type string
The category for the filter
location_tree Array of objects
The available locations
Array () [
{
display_name string
The name for the region and asset class
type string
Asset Class
locations Array of objects
List of available locations
Array () [
{
display_name string
Name of the location
type string
Formatted asset_Class.Exchange
}, ] } ]
Once you know the available params, send the endpoint /iserver/scanner/run to run a market scanner.
POST https://localhost:5000/v1/api/iserver/scanner/run
Request Body:
{
instrument string
The asset class, this would be the type returned in instrument_list
type string
The scanner parameter, this would be the code returned in scan_type_list
filter Array of objects
List of filters
Array () [
{
code string
The filter value, this would be the filters from instrument_list
value number
The value of the filter
},
]
location string
The region and asset class formatted
size number
The number of contracts returned. A max of 50 is returned.
]
Response:
contracts Array of objects
List of contracts returned
Array () [
{
server_id: number
Position Number max of 50 returned.
column_name string
Market Data column that should be included with scanner list.
symbol string
Contract Symbol
conidex string
Format either conid@exchange or conid
con_id string
Contract identifier
available_chart_periods string
The chart period available for contract
company_name string
Company Name of the contract
contract_description_1 string
IBKR contract symbol
listing_exchange string
Listing exchange
sec_type string
Asset Class
},
]
scan_data_column_name string
Name of market data column displayed for scanner.
]
Please be sure to authenticate first in order to resolve the below URLs.
For authentication details, visit https://interactivebrokers.github.io/cpwebapi/index.html#login
Example:
Using the endpoint /iserver/scanner/params to see what scanner parameters are available.
Request:
POST https://localhost:5000/v1/api/iserver/scanner/params
Response:
{
"scan_type_list": [
{
"display_name": "Top % Gainers",
"code": "TOP_PERC_GAIN",
"instruments": [
"STK",
"FUT.US",
"IND.US",
"STOCK.NA",
"STOCK.EU",
"FUT.EU",
"IND.EU",
"SSF.EU",
"STOCK.HK",
"FUT.HK",
"SSF.HK"
]
},
{
"display_name": "Most Active",
"code": "MOST_ACTIVE",
"instruments": [
"STK",
"FUT.US",
"SLB.US",
"STOCK.NA",
"STOCK.EU",
"FUT.EU",
"SSF.EU",
"STOCK.HK",
"FUT.HK",
"SSF.HK"
]
},
…
],
"instrument_list": [
{
"display_name": "US Stocks",
"type": "STK",
"filters": [
"afterHoursChangePerc",
"avgOptVolume",
"avgPriceTarget",
"avgRating",
"avgAnalystTarget2PriceRatio",
"avgVolume",
"avgUsdVolume",
"changeOpenPerc",
"changePerc",
"curEMA20",
"curEMA50",
"curEMA100",
…
],
"filter_list": [
{
"group": "afterHoursChangePercAbove",
"display_name": "After-Hours Change (%) Above",
"code": "afterHoursChangePercAbove",
"type": "non-range"
},
{
"group": "afterHoursChangePercBelow",
"display_name": "After-Hours Change (%) Below",
"code": "afterHoursChangePercBelow",
"type": "non-range"
},
{
"group": "avgOptVolumeAbove",
"display_name": "Average Opt. Volume Above",
"code": "avgOptVolumeAbove",
"type": "non-range"
},
…
],
"location_tree": [
{
"display_name": "US Stocks",
"type": "STK",
"locations": [
{
"display_name": "Listed/NASDAQ",
"type": "STK.US.MAJOR",
"locations": []
}
]
},
{
"display_name": "US Futures",
"type": "FUT.US",
"locations": [
{
"display_name": "GLOBEX",
"type": "FUT.GLOBEX"
},
…
}
]
}
]
} Sending the endpoint /iserver/scanner/run to query a market scanner.
Request:
POST
https://localhost:5000/v1/api/iserver/scanner/run
Request Body:
{
"instrument": "STK",
"type": "MOST_ACTIVE_USD",
"filter": [
{
"code": "priceAbove",
"value": 5
},
{
"code": "volumeAbove",
"value": 500
},
],
"location": "STK.US.MAJOR",
"size": "25"
}
Response:
{
"contracts": [
{
"server_id": "0",
"column_name": "Volume",
"symbol": "PTPI",
"conidex": "458378565",
"con_id": 458378565,
"available_chart_periods": "#R|1",
"company_name": "PETROS PHARMACEUTICALS INC",
"contract_description_1": "PTPI",
"listing_exchange": "NASDAQ.SCM",
"sec_type": "STK"
},
{
"server_id": "1",
"symbol": "PTN",
"conidex": "79464103",
"con_id": 79464103,
"available_chart_periods": "#R|1",
"company_name": "PALATIN TECHNOLOGIES INC",
"contract_description_1": "PTN",
"listing_exchange": "AMEX",
"sec_type": "STK"
},
{
"server_id": "2",
"symbol": "SQQQ",
"conidex": "440504393",
"con_id": 440504393,
"available_chart_periods": "#R|1",
"company_name": "PROSHARES ULTRAPRO SHORT QQQ",
"contract_description_1": "SQQQ",
"listing_exchange": "NASDAQ.NMS",
"sec_type": "STK"
},
…
}
],
"scan_data_column_name": "Volume"
}
If you have any further questions or issues creating a market scanner, please reach out to the API Group,
https://www.interactivebrokers.com/en/index.php?f=47047
Visit the IBKR API Center for Downloads, Resources, and Technical Details:
https://www.interactivebrokers.com/en/trading/ib-api.php
Disclosure: Interactive Brokers
The analysis in this material is provided for information only and is not and should not be construed as an offer to sell or the solicitation of an offer to buy any security. To the extent that this material discusses general market activity, industry or sector trends or other broad-based economic or political conditions, it should not be construed as research or investment advice. To the extent that it includes references to specific securities, commodities, currencies, or other instruments, those references do not constitute a recommendation by IBKR to buy, sell or hold such investments. This material does not and is not intended to take into account the particular financial conditions, investment objectives or requirements of individual customers. Before acting on this material, you should consider whether it is suitable for your particular circumstances and, as necessary, seek professional advice.
Supporting documentation for any claims and statistical information will be provided upon request.
Any stock, options or futures symbols displayed are for illustrative purposes only and are not intended to portray recommendations.
Disclosure: API Examples Discussed
Throughout the lesson, please keep in mind that the examples discussed are purely for technical demonstration purposes, and do not constitute trading advice. Also, it is important to remember that placing trades in a paper account is recommended before any live trading.
