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
_minor_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
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 name | Rule |
|---|---|
low_price_to_earnings | Trailing P/E between 0 and 15. |
high_dividend_yield_large_market_cap | Trailing 12-month dividend yield of 3% or more and market cap of Rs 20,000 crore or more. |
low_leverage_high_roe | Debt-to-equity of 0.5 or less and return on equity of 15% or more. |
high_promoter_holding_low_pledge | Promoter holding of 50% or more and pledged promoter shares of 5% or less. |
high_growth_latest_results | Latest-quarter revenue and net income each up 20% or more on the same quarter a year earlier, with net margin flat or higher. |
Endpoints
| MCP tool | REST route | What it returns |
|---|---|---|
| screen_stocks | GET /v1/screen | Filter the entire market by valuation, quality and ownership metrics |
| screen_by_query | POST /v1/screen/query | Screen companies with a numerical query expression |
| list_preset_screens | GET /v1/presets | The fixed, nightly-precomputed screens |
| run_preset_screen | GET /v1/presets/{name} | Run one of the fixed preset screens |
| search_stocks | GET /v1/search | Find a company by name, symbol, BSE code or ISIN |
| get_peer_comparison | GET /v1/stocks/{q}/peers | Auto-selected peer group with valuation & profitability medians |
| get_relevant_peers | GET /v1/stocks/{q}/relevant-peers | Purpose-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 -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
{
"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
Limits
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