Skip to main content

API to search for instruments across exchanges and segments. This API provides a comprehensive search functionality to find instruments based on free text query, exchanges, instrument types, segments, expiry keywords and ATM offset. Results are paginated for efficient data retrieval.

Key Features​

  • Free Text Search: Search by symbol, name, strike price or instrument type with support for partial matches.

  • Multiple Filters: Filter results by exchanges (NSE, BSE, MCX), segments (EQ, FO, CURR, etc.), and instrument types (PE, CE, etc.)

  • Expiry Filtering: Filter derivative instruments by expiry keywords or specific expiry dates as below:

    TypeDetails
    Weekly keywordscurrent_week, this_week, near_week, weekly, next_week, far_week
    Monthly keywordscurrent_month, this_month, near_month, monthly, next_month, far_month
    Date formatyyyy-MM-dd (e.g. 2025-10-30, 2025-11-27)

  • ATM Search: Search for ATM instruments by specifying the atm_offset to express relative distance from ATM.
    For example:
    Suppose Nifty is at 24,500 and the strike interval is 50.
    Use query=NIFTY, instrument_types=CE or PE, and expiry (e.g. current_week).
    With atm_offset=0 you get options at the ATM strike (24,500).
    With atm_offset=2 you get options two strikes above ATM (24,600).
    With atm_offset=-2 you get options two strikes below ATM (24,400).

  • Pagination: Control result size with page number and records per page parameters.

Note
  • This is an alternative way to get Instrument details instead of using the Instruments JSON files. And also the response is same as the Instrument JSON files.
  • For comma-separated lists (exchanges, segments, instrument_types), do not include spaces between values.
  • Search is case-insensitive and supports partial matches for symbol, name, and short name. Since its a free text search, results might not always be accurate.
  • To improve search performance, use more specific filter parameters like exchanges, segments and expiry.

What may not work well with free text search ?​

The following types of query values may not work well or may return unexpected results:

  • Very generic or single-character queries: A single letter or digit (e.g. 1, A) may match too many instruments or behave unpredictably. Use exchanges, segments, or instrument_types to narrow results.
  • Numeric-only (e.g. strike only): A query like 24000 without a symbol may match many option strikes across underlyings. Prefer including the symbol (e.g. NIFTY 24000) or use expiry and instrument_types to filter.
  • Multiple underlyings in one query: e.g. RELIANCE NIFTY may not be interpreted as two symbols. Use one symbol per request or make separate calls.
  • Identifiers not in search scope: Search matches on symbol, name and short name only. Other fields (e.g. ISIN, exchange_token) are not searchable via query; use Instrument JSON files to look up by those fields if needed.
  • Special characters: Unusual punctuation or symbolic characters in query may not improve matching. Prefer alphanumeric characters and spaces.

Request​

curl --location 'https://api.upstox.com/v2/instruments/search?query=Reliance&expiry=current_month&atm_offset=0&page_number=1&records=20' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}'

Additional samples in various languages are available in the Sample Code section on this page.


Query Parameters​

NameTypeRequiredDescription
querystringtrueFree text search with a maximum of 50 characters (e.g. RELIANCE, RELIANCE CE 1500, RELIANCE 28 Oct 2025)
exchangesstringfalseComma-separated list of exchanges
(e.g. NSE,BSE,MCX)
Each exchange value must be one of: [ALL, NSE, BSE, MCX]
Default: ALL
segmentsstringfalseComma-separated list of segments
(e.g. EQ,FO,CURR,COMM)
Each segment value must be one of: [ALL, EQ, FO, CURR, COMM, INDEX, OPT, FUT]
Default: ALL
instrument_typesstringfalseComma-separated list of instrument types
(e.g. CE,PE,A)
Each instrument type value must be either an option type [CE, PE] or an instrument series such as [A, X] etc.
expirystringfalseComma-separated list of expiry keywords or expiry dates.
Expiry keywords for weekly/monthly (see Key Features) or Use specific dates in format yyyy-MM-dd (e.g. 2025-10-30,2025-11-27), or.
atm_offsetintegerfalseRelative distance from ATM when searching options.
0 = ATM,
positive value → strikes above ATM
(e.g. 2 = ATM + 2 strikes)
negative → strikes below ATM
(e.g. -2 = ATM − 2 strikes).
if no expiry is provided, then by default current week options are searched for the given atm_offset.
page_numberintegerfalsePage number for pagination
(starting from 1)
Default: 1
recordsintegerfalseNumber of records per page
Default: 10, Maximum: 30
Responses

Response Body​

{
    "name": "RELIANCE INDUSTRIES LTD",
    "segment": "NSE_EQ",
    "exchange": "NSE",
    "isin": "INE002A01018",
    "instrument_key": "NSE_EQ|INE002A01018",
    "exchange_token": "2885",
    "trading_symbol": "RELIANCE",
    "short_name": "Reliance Industries",
    "tick_size": 10.0,
    "lot_size": 1,
    "instrument_type": "EQ",
    "freeze_quantity": 100000.0,
    "qty_multiplier": 1,
    "security_type": "NORMAL"
}

Field Description

Field NameTypeDescription
segmentstringSegment to which the instrument is associated.
Possible values: NSE_EQ, NSE_INDEX, NSE_FO, NCD_FO, BSE_EQ, BSE_INDEX, BSE_FO, BCD_FO, MCX_FO, NSE_COM
namestringThe name of the equity.
exchangestringExchange to which the instrument is associated.
Possible values: NSE, BSE, MCX
isinstringThe International Securities Identification Number.
instrument_typestringThe instrument types for NSE are present at NSE India and for BSE are present at BSE India.
instrument_keystringThe unique identifier used across Upstox APIs for instrument identification. For the regex pattern applicable to this field, see the Field Pattern Appendix.
lot_sizenumberThe size of one lot of the equity.
freeze_quantitynumberThe maximum quantity that can be frozen.
exchange_tokenstringThe exchange-specific token for the equity.
tick_sizenumberThe minimum price movement of the equity.
trading_symbolstringTrading symbol of the instrument.
short_namestringA shorter or abbreviated name of the equity.
security_typestringIdentifies the classification or status of a security within the market. Valid security types can be found in the Security Type Appendix
qty_multipliernumberQuantity multiplier for the instrument.

Sample Code​

curl --location 'https://api.upstox.com/v2/instruments/search?query=RELIANCE&exchanges=NSE&segments=FO&instrument_types=CE,PE&expiry=current_month&atm_offset=0&page_number=1&records=20' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}'
Loading...