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
]
}, - display_name string
- 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
]
- display_name string
- 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
- group string
- 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
- display_name string
- display_name string
}
]
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
},
] - code string
- 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
},
]
- server_id: number
- 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, ref: 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.
The views and opinions expressed herein are those of the author and do not necessarily reflect the views of Interactive Brokers, its affiliates, or its employees.
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.
Disclosure: Security Futures
Security futures involve a high degree of risk and are not suitable for all investors. The amount you may lose may be greater than your initial investment. Before trading security futures, please read the Security Futures Risk Disclosure Statement. For a copy visit ibkr.com
Disclosure: Futures Trading
Futures are not suitable for all investors. The amount you may lose may be greater than your initial investment. Before trading futures, please read the CFTC Risk Disclosure. A copy and additional information are available at ibkr.com.
Join The Conversation
If you have a general question, it may already be covered in our FAQs. If you have an account-specific question or concern, please reach out to Client Services.