Skip to main content

Instrument Search API Beta​

Effective Date: March 17, 2026

We are pleased to announce the Instrument Search API, which lets you search for instruments by free text query and filters—without downloading or parsing the full Instrument JSON files.

Today, many integrations use the Instrument JSON files (BOD, MTF, MIS, etc.) to look up instrument_key, symbol, segment, expiry, and other details. That approach works well when you need the full universe of instruments or offline processing.

The Instrument Search API is a better fit when you need to:

  • Look up a few instruments by symbol, name, or contract (e.g. RELIANCE, NIFTY 24000 CE, etc.)
  • Filter by exchange, segment, instrument type, expiry, or ATM offset.
  • Get only the matching instruments with pagination, instead of handling large JSON downloads.

What’s available?​

  • Free text search with partial matching (symbol, name, strike, instrument type)
  • Filters: exchanges (NSE, BSE, MCX), segments (EQ, FO, etc.), instrument types (CE, PE, FUT, etc.)
  • Expiry: Support for specific keywords (e.g. current_month, next_week etc.) and specific dates (yyyy-MM-dd)
  • ATM offset: search by distance from ATM (e.g. 0 for ATM, 2 for ATM+2, -2 for ATM-2)
  • Paginated response with detailed instrument fields (instrument_key, lot_size, strike_price, expiry, tick_size, etc.)

When to use what?​

NeedUse
Search by query or filters, small result setInstrument Search API
Full instrument list (BOD), MTF, MIS, or suspended listsInstrument JSON files

Thank You​

We appreciate your support. If you have questions or feedback, reach out via the Upstox Developer Community.