Options Smartlist

API for retrieving a ranked list of options contracts filtered by asset type and category. Each entry includes the instrument key, live price data, and the category-specific metric used for ranking.

A smartlist is a curated, real-time ranked list of instruments grouped by a specific market signal — such as highest traded value, biggest open interest change, or strongest implied volatility move. Instead of scanning the entire options market, you get a focused subset of contracts that are most relevant to a given category at that moment.

For more information on how the options smartlist feature works, see the Upstox community post.

Request

curl --location 'https://api.upstox.com/v2/market/smartlist/options?asset_type=INDEX&category=TOP_TRADED&page_number=1&page_size=20' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}'

For additional samples in various languages, please refer to the Sample code section on this page.

Query Parameters

Name	Required	Description
asset_type	true	Asset type. Accepted values: INDEX, STOCK, COMMODITY.
category	true	Ranking category. Accepted values depend on asset_type — see the table below.
page_number	false	Page number, 1-indexed. Defaults to 1.
page_size	false	Number of records per page. Maximum 50.

Accepted category values by asset_type:

asset_type	Accepted category values
INDEX, STOCK	TOP_TRADED, MOST_ACTIVE, OI_GAINERS, OI_LOSERS, PRICE_GAINERS, PRICE_LOSERS, IV_GAINERS, IV_LOSERS, UNDER_5000, UNDER_10000
COMMODITY	TOP_TRADED, MOST_ACTIVE, OI_GAINERS, OI_LOSERS

The metric_key field in the response indicates which metric was used for ranking:

category	metric_key
TOP_TRADED	total_traded_value
MOST_ACTIVE	volume_traded_today
OI_GAINERS, OI_LOSERS	open_interest
PRICE_GAINERS, PRICE_LOSERS	price
IV_GAINERS, IV_LOSERS	implied_volatility
UNDER_5000, UNDER_10000	buy_margin

Responses

• 200
• 4XX

---

Response body

{
  "status": "success",
  "data": {
    "asset_type": "INDEX",
    "category": "TOP_TRADED",
    "time_stamp": 1780041069287,
    "metric_key": "total_traded_value",
    "smartlist": [
      {
        "instrument_key": "NSE_FO|57047",
        "price": {
          "current": 177.4,
          "close_price": 125.5,
          "change_abs": 51.9,
          "change_pct": 41.35
        },
        "metric": {
          "current": 53889598074,
          "previous": 4351865287721.25,
          "change_abs": -4297975689647.25,
          "change_pct": -98.76
        }
      },
      {
        "instrument_key": "NSE_FO|57051",
        "price": {
          "current": 241.65,
          "close_price": 172.35,
          "change_abs": 69.3,
          "change_pct": 40.21
        },
        "metric": {
          "current": 36473443958.25,
          "previous": 2391714654137.25,
          "change_abs": -2355241210179,
          "change_pct": -98.48
        }
      },
      {
        "instrument_key": "NSE_FO|57049",
        "price": {
          "current": 208.15,
          "close_price": 148,
          "change_abs": 60.15,
          "change_pct": 40.64
        },
        "metric": {
          "current": 29500456316.5,
          "previous": 2171128196155.75,
          "change_abs": -2141627739839.25,
          "change_pct": -98.64
        }
      }
    ],
    "page_number": 1,
    "page_size": 3,
    "total_pages": 3354
  }
}

• For UNDER_5000 and UNDER_10000 categories, metric.previous, metric.change_abs, and metric.change_pct are returned as null — no previous metric value is available for these categories.

Name	Type	Description
status	string	Outcome of the request. Typically success for successful operations.
data	object	Response data object.
data.asset_type	string	Asset type from the request.
data.category	string	Category from the request.
data.time_stamp	integer	Unix timestamp in milliseconds when the data was generated.
data.metric_key	string	The metric used for ranking in this response.
data.smartlist	array	Ranked list of options instruments.
data.smartlist[].instrument_key	string	Unique instrument identifier. See Instrument keys.
data.smartlist[].price.current	number	Last traded price (LTP).
data.smartlist[].price.close_price	number	Previous close price.
data.smartlist[].price.change_abs	number	Absolute price change (current - close_price).
data.smartlist[].price.change_pct	number	Percentage price change.
data.smartlist[].metric.current	number	Current value of the ranking metric.
data.smartlist[].metric.previous	number | null	Previous value of the ranking metric. null for UNDER_5000 and UNDER_10000.
data.smartlist[].metric.change_abs	number | null	Absolute change in the metric. null for UNDER_5000 and UNDER_10000.
data.smartlist[].metric.change_pct	number | null	Percentage change in the metric. null for UNDER_5000 and UNDER_10000.
data.page_number	integer	Current page number.
data.page_size	integer	Number of records in the current page.
data.total_pages	integer	Total number of pages available.

Error codes

Error code	Description
UDAPI1212	Invalid asset_type — The asset_type value must be INDEX, STOCK, or COMMODITY.
UDAPI1213	Invalid category for the given asset_type — The category value is not supported for the provided asset_type.
UDAPI1214	Invalid page_size — The page_size value exceeds the maximum allowed value of 50.

Sample Code

Get options smartlist

Curl

curl --location 'https://api.upstox.com/v2/market/smartlist/options?asset_type=INDEX&category=TOP_TRADED&page_number=1&page_size=20' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}'

Python

import requests

url = 'https://api.upstox.com/v2/market/smartlist/options'
params = {
    'asset_type': 'INDEX',
    'category': 'TOP_TRADED',
    'page_number': 1,
    'page_size': 20,
}
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer {your_access_token}'
}

response = requests.get(url, params=params, headers=headers)
print(response.text)

Node.js

const axios = require('axios');

const url = 'https://api.upstox.com/v2/market/smartlist/options';
const params = {
  asset_type: 'INDEX',
  category: 'TOP_TRADED',
  page_number: 1,
  page_size: 20,
};
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {your_access_token}'
};

axios.get(url, { params, headers })
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.upstox.com/v2/market/smartlist/options"
            + "?asset_type=INDEX"
            + "&category=TOP_TRADED"
            + "&page_number=1"
            + "&page_size=20";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("Accept", "application/json")
            .header("Authorization", "Bearer {your_access_token}")
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php

$query = http_build_query([
    'asset_type'  => 'INDEX',
    'category'    => 'TOP_TRADED',
    'page_number' => 1,
    'page_size'   => 20,
]);

$url = 'https://api.upstox.com/v2/market/smartlist/options?' . $query;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer {your_access_token}',
]);

$response = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
}
curl_close($ch);
echo $response;
?>

Loading...