Standard screeners

This API runs a Standard screener and returns the stocks, contracts or ETFs that meet its conditions, with the fields you choose.

USE CASE

Find today's top gainers in a universe, stock futures with long build-up in the last 15 minutes, or stocks near their 52-week high, and get the values you need for each one in a single call.

Note

One call returns at most 500 rows and 10 fields. There is no paging: to see other rows, change the sort or narrow the universe.

Details

Send your App ID and access token in the Authorization header as APP_ID:ACCESS_TOKEN. Only GET is supported.
This API is part of the Data APIs and works with access tokens of all app types (100, 102 and 200).
There are 111 Standard screeners in 10 categories: Intraday Screeners, Breakout with Volume, Fresh Breakouts, Near Breakouts, Technical Crossovers and Momentum, Fundamentals, Futures Scan, Options Trading, Commodities Futures and ETF. Take ids, rules and defaults from the Configuration API.
Parameters are sent in the URL query string (names are case-sensitive, values are not). See Request Attributes below.
A parameter works only if it is in the screener's supported_params. Any other parameter returns HTTP 400, including limit, offset and page.
symbolticker is always returned first and does not count towards the 10 fields.
The timeframe sets the period of Selected Time Frame in the screener's conditions and of its default sort field, for example t0_5min_per_change_oi becomes t0_15min_per_change_oi. For a screener whose conditions use only Day's values, it changes the default sort field only.
Every returned row meets the screener's conditions. The sort decides the row order and, when more than 500 rows match, which 500 are returned. The default sorts put the strongest matches first.
The response holds header (one object per column: unique_key, description, data_type and, for most fields, tool_tip) and body (one array per row, values in header order). body is empty when nothing matches.
The response also returns the settings that were applied, including defaults: universe, timeframe, expiry, option_type, order_by and order. A setting is null when the screener does not use it, or when all expiries or both option types are returned.
fetch_time is when the response was built and last_update_time is when the screener's data was last refreshed, both in Unix epoch seconds.
How fresh the data is: during market hours results are real time, so both times equal the time of your call and move with the clock. After the close, last_update_time shows the last refresh: 15:30 IST for equity and ETF screeners and 15:40 IST for F&O screeners. Commodity screeners keep refreshing while MCX is open.

Plan limits

Standard plan

50 requests per day

Prime plan

As per Prime API rate limits: 10 requests per second, 500 per minute and 5,00,000 per day

For rate limits and all other plan details, see Plans & rate limits.

Request Attributes

Attribute	Data Type	Description
`screener_id`*	string	Mandatory. Screener `id` from the `screeners_standard` array in the config response. Eg: `top_gainers`
`fields`	string	Optional. Comma-separated list of column or timeframe `id`s. Maximum 10 fields. `symbolticker` is always included in the response.
`universe`	string	Optional. Cash-market universe `id` from the `universes` array only. Default: `iw010` (Nifty 500).
`order_by`	string	Optional. Column or timeframe `id` used to sort results.
`order`	string	Optional. Sorting direction. Allowed values: `asc`, `desc`.

Response Attributes

Attribute	Data Type	Description
`s`	string	ok / error
`code`	int	This is the code to identify specific responses
`message`	string	This is the message to identify the specific error responses
`data`	object	Result payload
`data.header`	array	Column metadata for the result set
`data.body`	array	Result rows
`data.error`	string	Error detail when applicable
`data.last_update_time`	int	Epoch timestamp of the last data update

Finding a field and its meaning

Look the field up in columns of the Configuration API. Each entry gives id (what you send in fields and order_by), name (the label) and category.
The 118 fields fall in 12 categories: Others, Price & Volume, Returns, F&O, Valuation Ratios, Growth, Margin & Profitability, P&L - Annual, Quarterly, Balance Sheet, Solvency & Liquidity and Cash Flow.
A screener accepts only the fields of its column_group. Take them from column_groups[column_group] in the same response.
The header of a Standard response repeats each field: unique_key is the field id and description is its name. Most fields also carry a tool_tip with a short explanation; where tool_tip is missing, the name is the only description.

Timeframe ids

The full list is in timeframes of the Configuration API. A screener accepts only its allowed_timeframes.

timeframe	Meaning	timeframe	Meaning
`t0_1min`	1 min	`c3_month`	3 months
`t0_5min`	5 min	`c6_month`	6 months
`t0_15min`	15 min	`ytd`	YTD
`t0_30min`	30 min	`c52_week`	52 weeks
`t0_60min`	1 hour	`c2_year`	2 years
`t0`	1 day	`c3_year`	3 years
`c1_week`	1 week	`c5_year`	5 years
`c1_month`	1 month	`alltime`	All time

Universe ids used on this page

All ids and names are in universes, universes_futures and universes_options of the Configuration API.

universe	Attribute
`iw001`	Nifty 50
`iw010`	Nifty 500
`cs001`	All Stocks
`fw001`	Index Based Futures
`fw002`	Stock Based Futures
`ow001`	Index Based Options
`ow002`	Stock Based Options
`cw001`	Commodity Based Futures

Example requests

The query string is shown here; the endpoint is above.

Top gainers over one week, with last price: screener_id=top_gainers&timeframe=c1_week&fields=t0_close_ltp
Futures OI gainers on universe fw002: screener_id=fut_oi_gainers&universe=fw002&fields=t0_close_ltp
Options OI gainers for one expiry, calls only: screener_id=top_oi_gainers&universe=ow001&expiry=EPOCH&option_type=CE&fields=t0_close_ltp, where EPOCH is a value from expiries.ow001

Errors

HTTP	code	When	message
400	-50	`screener_id` missing	`screener_id is required`
400	-50	`screener_id` unknown	`invalid screener_id`
400	-50	More than 10 fields	`maximum 10 fields are allowed`
400	-50	A value the screener does not accept	`invalid field FIELD for screener ID; see column_groups.GROUP in /config`, and the same for universe, timeframe and expiry
400	-50	A parameter the screener does not support	`PARAMETER is not supported for screener ID` or `unsupported query parameter: NAME`
401	-16	Missing or wrong token	`Could not authenticate the user`
404	-50	Wrong path	`endpoint not found`
405	-50	Method other than GET	`method not allowed; use GET`
429		Rate limit crossed	Wait, then retry

A failed call returns "s": "error"; a successful one returns "s": "ok". In the messages above, FIELD, ID, GROUP, PARAMETER and NAME stand for the values in your request.

Notes

A parameter sent with a blank value counts as not sent, but only if the screener supports that parameter.
Prices and money values (ttv, market_cap, balance-sheet and P&L fields) are in rupees, not crore. Fields named (%) are percentages: 2.5 means 2.5%. The conditions text writes amounts in crore (cr) and rupees (Rs).
Some money values carry long decimals, for example 40574899902.34375. Round them for display.
leverage (MTF Leverage) is text, such as 2.5x, or - when the stock is not eligible for MTF.
expiry is returned in Unix epoch seconds; expiry_type is W (weekly) or M (monthly).
pnl_1pct_move (Near Expiry - Commodities) is the profit or loss on one lot for a 1% price move: LTP × units per lot × 1%, rounded.
An empty body is a valid answer: it means no row meets the conditions at that moment.

Request

from fyers_apiv3 import fyersModel

client_id = "XC4XXXXM-100"
access_token = "eyJ0eXXXXXXXX2c5-Y3RgS8wR14g"

fyers = fyersModel.FyersModel(client_id=client_id, token=access_token, is_async=False, log_path="")

data = {
    "screener_id": "top_gainers",
    "fields": "t0_close_ltp,t0_per_change,t0_volume"
}

response = fyers.screeners_standard(data=data)
print(response)

{
  "code": 200,
  "message": "",
  "s": "ok",
  "data": {
    "body": [
      [
        "NSE:PPLPHARMA-EQ",
        232.8,
        17.15,
        118072228
      ],
      [
        "NSE:SYNGENE-EQ",
        410.85,
        12.19,
        32965479
      ]
    ],
    "expiry": null,
    "fetch_time": 1793183914,
    "header": [
      {
        "data_type": "string",
        "description": "Symbol",
        "unique_key": "symbolticker"
      },
      {
        "data_type": "double",
        "description": "Price",
        "tool_tip": "Latest traded price of the stock or contract.",
        "unique_key": "t0_close_ltp"
      },
      {
        "data_type": "double",
        "description": "1D Chg (%)",
        "tool_tip": "Percentage change in price from the previous trading session's close.",
        "unique_key": "t0_per_change"
      },
      {
        "data_type": "double",
        "description": "Volume",
        "tool_tip": "Total quantity traded during the current trading session.",
        "unique_key": "t0_volume"
      }
    ],
    "last_update_time": 1793181600,
    "option_type": null,
    "order": "desc",
    "order_by": "t0_per_change",
    "timeframe": "t0",
    "universe": "iw010"
  }
}