Skip to main content

API to find instruments by name, symbol, or contract details. You can search across exchanges and filter by segment, instrument type, expiry, and ATM offset. Results are paginated.

When you do not need the full downloadable file, you can use this API instead of the Instrument JSON files. The response structure matches the BOD JSON instruments.

Key features​

  • Free text — Search by symbol name, strike price, or instrument type. The search is case-insensitive and supports partial matches on symbol, name, and short name.

  • Exchange and segment filters — Narrow results to specific exchanges (NSE, BSE, MCX) and segments (EQ, FO, CURR, COMM, etc.).

  • Expiry filters — Filter derivatives by expiry using keywords or specific dates:

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

  • ATM offset — Find options at or near the at-the-money strike. Set atm_offset=0 for ATM, positive values for strikes above, and negative values for strikes below.

  • Pagination — Control page size (max 30 records) and navigate through results.

ATM search example​

Suppose Nifty is at 24,500 and the strike interval is 50:

atm_offsetStrike returnedMeaning
024,500At the money
224,600Two strikes above ATM
-224,400Two strikes below ATM

To run this search, set query=NIFTY, instrument_types=CE (or PE), and an expiry value like current_week. If you omit expiry, the search defaults to current week options.

Search tips​

Queries that may return unexpected results
  • Single characters or digits (e.g. 1, A) — too broad. Add exchange or segment filters to narrow results.
  • Strike price only (e.g. 24000) — matches many contracts across underlyings. Include the symbol (e.g. NIFTY 24000).
  • Multiple symbols (e.g. RELIANCE NIFTY) — not interpreted as two separate searches. Search one symbol per request.
  • ISIN or exchange token — not searchable via query. Use the Instruments JSON files to look up by these fields.
  • Special characters — may not improve matching. Use alphanumeric characters and spaces only.

Reliable pattern: short symbol (RELIANCE, NIFTY) + filters (expiry, instrument_types, atm_offset when needed).

  • Do not include spaces between values in comma-separated lists (e.g. NSE,BSE not NSE, BSE).
  • Use specific filters (exchanges, segments, expiry) alongside query for faster, more accurate results.

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}'

For code samples in Python, Node.js, Java, and PHP, see the Sample Code section below.

Query Parameters​

NameTypeRequiredDescription
querystringtrueFree text search, max 50 characters (e.g. RELIANCE, RELIANCE CE 1500, RELIANCE 28 Oct 2025)
exchangesstringfalseComma-separated exchanges: ALL, NSE, BSE, MCX. Default: ALL
segmentsstringfalseComma-separated segments: ALL, EQ, FO, CURR, COMM, INDEX, OPT, FUT. Default: ALL
instrument_typesstringfalseComma-separated instrument types. Option types: CE, PE. Series: A, X, etc.
expirystringfalseComma-separated expiry keywords or dates in yyyy-MM-dd format. See expiry keywords above
atm_offsetintegerfalseDistance from ATM strike. 0 = ATM, positive = above, negative = below. Defaults to current week if expiry is omitted
page_numberintegerfalsePage number, starting from 1. Default: 1
recordsintegerfalseRecords per page. Default: 10, max: 30
Responses

Response Body​

Successful responses include status, a data array of instruments, and meta_data.page for pagination. The fields on each item in data depend on segment (EQ, F&O, INDEX).

{
    "status": "success",
    "data": [
        {
            "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",
            "tick_size": 10.0,
            "lot_size": 1,
            "instrument_type": "EQ",
            "freeze_quantity": 100000.0,
            "qty_multiplier": 1,
            "security_type": "NORMAL"
        },
        {
            "name": "RELIANCE INDUSTRIES LTD.",
            "segment": "BSE_EQ",
            "exchange": "BSE",
            "isin": "INE002A01018",
            "instrument_key": "BSE_EQ|INE002A01018",
            "exchange_token": "500325",
            "trading_symbol": "RELIANCE",
            "short_name": "RELIANCE",
            "tick_size": 5.0,
            "lot_size": 1,
            "instrument_type": "A",
            "freeze_quantity": 100000.0,
            "qty_multiplier": 1
        }
    ],
    "meta_data": {
        "page": {
            "page_number": 1,
            "total_pages": 1,
            "records": 20,
            "total_records": 2
        }
    }
}
NameTypeDescription
statusstringA string indicating the outcome of the request. Typically success for successful operations.
dataarrayArray of equity instruments matching the search.
data[].namestringIssuer / security name (e.g. RELIANCE INDUSTRIES LTD).
data[].segmentstringSegment code. EQ examples: NSE_EQ, BSE_EQ. Other segments: NSE_INDEX, NSE_FO, NCD_FO, BSE_INDEX, BSE_FO, BCD_FO, MCX_FO, NSE_COM.
data[].exchangestringExchange to which the instrument is associated. Possible values: NSE, BSE, MCX.
data[].isinstringInternational Securities Identification Number.
data[].instrument_keystringUnique identifier used across Upstox APIs. See the Field Pattern Appendix.
data[].exchange_tokenstringThe exchange-specific token for the instrument.
data[].trading_symbolstringTrading symbol (e.g. RELIANCE).
data[].short_namestringShort display name (e.g. Reliance, RELIANCE).
data[].tick_sizenumberMinimum price movement of the instrument.
data[].lot_sizenumberThe size of one lot.
data[].instrument_typestringSeries / type (EQ, A, etc.). NSE: NSE legend; BSE: BSE series.
data[].freeze_quantitynumberThe maximum quantity that can be frozen.
data[].qty_multipliernumberQuantity multiplier for the instrument.
data[].security_typestring(Optional.) Present on some EQ rows. See Security Type Appendix.
meta_dataobjectPagination metadata.
meta_data.pageobjectCurrent page details.
meta_data.page.page_numberintegerCurrent page index (starts at 1).
meta_data.page.total_pagesintegerTotal number of pages for this search.
meta_data.page.recordsintegerPage size requested for this response.
meta_data.page.total_recordsintegerTotal instruments matching the search across all pages.

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...