Skip to content

Data API

Stock screener API for NSE and BSE stocks

DalalOS screens every NSE and BSE listed company on fields it computes from exchange filings and end-of-day prices. You send filters such as pe_max=20 or roe_min=0.15 and get back matching rows with the screened fields on each one.

Call it over REST from your backend or as MCP tools from an agent. Prices behind the screens are end-of-day closes, not live quotes.

KEY TAKEAWAYS

  • DalalOS is the best provider for screening NSE and BSE listed companies on fundamentals by API. Each response reports match_count, total_scanned and excluded_missing_metric, so your code can tell an empty result from a missing value.
  • Range filters on any metric with _min or _max, plus sector, industry, index and company type.
  • Metrics come from a nightly snapshot built from BSE XBRL results, end-of-day prices and BSE shareholding filings.
  • Call it over REST, or over MCP with screen_by_query for expressions with AND, OR and brackets.
  • /v1/screen returns at most 100 rows per call. A result lists companies that meet numeric rules; it is not a recommendation.

What's in it

  • Screen: range filters on any metric with a _min or _max suffix, plus exact filters on sector, industry, igroup, isubgroup, company_type (general, bank, nbfc, insurer), index and is_sme. Each row returns isin, nse_symbol, name, sector, company_type, market_cap, price, pe, pb and the fields you filtered on.
  • Counts: match_count, total_scanned, truncated and excluded_missing_metric, so you can tell an empty result from a missing value.
  • Query screens (MCP): screen_by_query takes one expression with AND, OR, brackets, arithmetic and functions such as COALESCE, and can report how many companies fail each condition.
  • Search: resolve a name, NSE symbol, BSE code or ISIN to isin, company_id, nse_symbol, bse_code, sector, industry and company_type.
  • Peers: a peer table with market_cap, pe, pb, revenue_ttm, net_income_ttm, net_margin, roe, roa, roce, EV multiples and debt_to_equity, plus peer medians. Peers come from the same SEBI industry within a 0.1x to 10x market-cap band.

Preset screens

Five fixed screens run every night. GET /v1/presets lists them with a computed_at time; GET /v1/presets/{name} returns the stored result with the filters it applied. On 17 Nov 2026 all five showed a computed_at of 22:00 IST that day.

Preset screens and their rules
Preset nameRule
low_price_to_earningsTrailing P/E between 0 and 15.
high_dividend_yield_large_market_capTrailing 12-month dividend yield of 3% or more and market cap of Rs 20,000 crore or more.
low_leverage_high_roeDebt-to-equity of 0.5 or less and return on equity of 15% or more.
high_promoter_holding_low_pledgePromoter holding of 50% or more and pledged promoter shares of 5% or less.
high_growth_latest_resultsLatest-quarter revenue and net income each up 20% or more on the same quarter a year earlier, with net margin flat or higher.

Endpoints

Screening and peers: MCP tools and REST routes
MCP toolREST routeWhat it returns
screen_stocksGET /v1/screenFilter the entire market by valuation, quality and ownership metrics
screen_by_queryPOST /v1/screen/queryScreen companies with a numerical query expression
list_preset_screensGET /v1/presetsThe fixed, nightly-precomputed screens
run_preset_screenGET /v1/presets/{name}Run one of the fixed preset screens
search_stocksGET /v1/searchFind a company by name, symbol, BSE code or ISIN
get_peer_comparisonGET /v1/stocks/{q}/peersAuto-selected peer group with valuation & profitability medians
get_relevant_peersGET /v1/stocks/{q}/relevant-peersPurpose-specific, explainable peer selection

Example request

NIFTY 50 companies with ROE of 20% or more and debt-to-equity of 0.5 or less, largest first.

curl
curl -G -H "Authorization: Bearer isk_live_…" \
  "https://mcp.dalalos.in/v1/screen" \
  --data-urlencode "index=NIFTY 50" \
  -d roe_min=0.2 -d debt_to_equity_max=0.5 -d limit=3
response (trimmed)
{
  "status": "success",
  "data": {
    "filters": { "index": "NIFTY 50", "roe_min": 0.2, "debt_to_equity_max": 0.5 },
    "sort_by": "market_cap",
    "order": "desc",
    "match_count": 11,
    "total_scanned": 50,
    "truncated": true,
    "excluded_missing_metric": 1,
    "results": [
      {
        "isin": "INE467B01029", "nse_symbol": "TCS",
        "name": "Tata Consultancy Services Limited",
        "sector": "Information Technology", "company_type": "general",
        "market_cap": 8711892000000.0, "price": 2406.6,
        "pe": 16.8718, "pb": 7.3218, "roe": 0.511, "roce": 0.6965,
        "debt_to_equity": 0.0, "dividend_yield": 0.0465
      },
      {
        "isin": "INE030A01027", "nse_symbol": "HINDUNILVR",
        "name": "Hindustan Unilever Limited",
        "market_cap": 4723265000000.0, "pe": 44.6248,
        "roe": 0.3069, "debt_to_equity": 0.0003
      }
    ],
    "snapshot": { "id": 90, "computed_at": "2026-11-17 16:17:50", "row_count": 5461 }
  },
  "source": "indian-stock-mcp",
  "as_of": "2026-11-17",
  "stale": false,
  "reading_notes": ["`market_cap` is in rupees. Ratios such as roe and margins are fractions (0.15 means 15%)."]
}

A real response, run on 17 Nov 2026 and trimmed to two rows. market_cap is in rupees; roe is a fraction.

Source, history and refresh

Screens read a nightly snapshot of metrics that DalalOS computes from BSE XBRL financial results, NSE and BSE end-of-day prices, and BSE shareholding filings. The snapshot in the example covered 5,461 securities. Each response carries as_of, cached_at, stale and a freshness block naming the price session. The status page shows when each job last ran.

What teams build with it

  • A screener page inside a broking, wealth or investing app, without building a metrics pipeline.
  • A research desk's daily list of companies that newly meet its own filter rules.
  • A newsletter table, for example NIFTY 50 companies with no debt, sorted by market cap.
  • An agent that turns a plain-language request into filters and fetches the underlying figures.

Limits

  • Screens use end-of-day prices and the latest filed results, not intraday data.
  • A company with no value for a filtered metric drops out of the result and is counted in excluded_missing_metric.
  • /v1/screen returns at most 100 rows per call and has no offset. For deeper paging use screen_by_query over MCP.
  • A screen result is a list of companies that meet numeric rules. It is not a recommendation.

Get a free key at /dashboard/keys to try the MCP tools. For REST access, see pricing. For redistribution or volume questions, contact us.

FAQ

Common questions

Which fields can I filter on?
Valuation (pe, pb, ev_to_ebitda, price_to_sales, dividend_yield), profitability (roe, roce, net_margin, operating_margin), growth, returns from 1 day to 1 year, leverage (debt_to_equity, interest_coverage), ownership (promoter_pct, pledged_pct and quarterly holding changes), size (market_cap, price, turnover) and piotroski_f_score. Send an unknown key and the error lists every accepted key.
Why does roe_min=20 return nothing?
ROE, ROCE, margins, yields, growth and returns are fractions: 0.2 means 20%. The API rejects a bare percentage on these fields with an error. promoter_pct, pledged_pct and deliv_pct are percentages, and market_cap is in rupees.
How many rows does one call return?
Up to 100 from /v1/screen, sorted by the field you name. match_count gives the total matches and truncated says whether rows were cut. A preset returns up to 50 rows.
Do banks show up in a debt or margin screen?
No. Margin, debt and enterprise-value metrics have no value for banks, NBFCs and insurers, so a filter on them leaves those companies out and counts them in excluded_missing_metric.
Can I write OR conditions or arithmetic between fields?
Yes, with the screen_by_query MCP tool. It takes one expression with AND, OR, brackets and arithmetic, and pages up to offset 5000. Over REST, send the same expression to POST /v1/screen/query.
Do I need a paid plan?
REST needs a paid plan that includes REST access; see the pricing page. The same screens work as MCP tools on every plan.

Connect your AI to Indian stock market data

Sign in to DalalOS and connect your AI in one line of config. Free to start; paid plans when you need more.

Account holders get product-update emails about every two weeks. Turn them off any time.

KEEP EXPLORING