Finviz API: Screen US stocks
Screens US-listed stocks on Finviz by sector, company size, minimum dividend yield, maximum P/E ratio and market signal, ranked by market value, today's gain or dividend yield.
Unofficial. Not affiliated with or endorsed by Finviz.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Page optional
page 1-based page of results to start from, for example 2.
1 (default)
Whole number 1 or more.
- Sort optional
sort Stock ranking, for example largest_first.
largest_first (default)
One of
largest_first,biggest_gainers,highest_dividend.- Sector optional
sector Business sector, for example Technology; any includes all sectors.
Technology
One of
any,Basic Materials,Communication Services,Consumer Cyclical,Consumer Defensive,Energy,Financial,Healthcare,Industrials,Real Estate,Technology,Utilities. Defaultany.- Signal optional
signal Market signal, for example top_gainers.
none (default)
One of
none,top_gainers,top_losers,new_52_week_high,new_52_week_low,unusual_volume,most_active,oversold,overbought.- Max Results optional
max_results Maximum number of stocks to return, for example 20. Up to 100.
20
Whole number from 1 to 100. Default
20.- Company Size optional
company_size Market value range, for example large ($10B–$200B).
mega
One of
any,mega,large,mid,small,micro. Defaultany.- Minimum Dividend Yield (%) optional
minimum_dividend_yield_percent Minimum annual dividend yield as a percentage, for example 2.5.
0 (default)
Number 0 or more.
- Maximum Price to Earnings Ratio optional
maximum_price_to_earnings_ratio Max P/E ratio, for example 25. Omit to include any P/E.
Not set
Number 0 or more.
Input as JSON
{ "sector": "Technology", "max_results": 20, "company_size": "mega"}Output
{ "stocks": [ { "sector": "Technology", "ticker": "NVDA", "company": "NVIDIA Corp", "country": "USA", "industry": "Semiconductors", "page_url": "https://finviz.com/quote.ashx?t=NVDA" , "price_usd": 228.86, "volume_shares": 142344321, "market_cap_usd": 5515530000000, "change_percent_today": 1.68, "price_to_earnings_ratio": 28.93 }, { "sector": "Technology", "ticker": "AAPL", "company": "Apple Inc", "country": "USA", "industry": "Consumer Electronics", "page_url": "https://finviz.com/quote.ashx?t=AAPL" , "price_usd": 338.4, "volume_shares": 32820848, "market_cap_usd": 4938670000000, "change_percent_today": -0.78, "price_to_earnings_ratio": 38.79 }, { "sector": "Technology", "ticker": "MSFT", "company": "Microsoft Corp", "country": "USA", "industry": "Software - Infrastructure", "page_url": "https://finviz.com/quote.ashx?t=MSFT" , "price_usd": 509.22, "volume_shares": 19626939, "market_cap_usd": 3781240000000, "change_percent_today": -1.35, "price_to_earnings_ratio": 28.38 } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"finviz.com/screen_stocks","input":{"sector":"Technology","max_results":20,"company_size":"mega"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "finviz.com/screen_stocks" , "input": { "sector": "Technology", "max_results": 20, "company_size": "mega" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "finviz.com/screen_stocks" , "input": { "sector": "Technology", "max_results": 20, "company_size": "mega" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run finviz.com/screen_stocks# with {"sector":"Technology","max_results":20,"company_size":"mega"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "properties": { "page": { "type": "integer", "default": 1, "minimum": 1, "description": "1-based page of results to start from, for example 2." }, "sort": { "enum": [ "largest_first", "biggest_gainers", "highest_dividend" ], "type": "string", "default": "largest_first", "description": "Stock ranking, for example largest_first." }, "sector": { "enum": [ "any", "Basic Materials", "Communication Services", "Consumer Cyclical", "Consumer Defensive", "Energy", "Financial", "Healthcare", "Industrials", "Real Estate", "Technology", "Utilities" ], "type": "string", "default": "any", "description": "Business sector, for example Technology; any includes all sectors." }, "signal": { "enum": [ "none", "top_gainers", "top_losers", "new_52_week_high", "new_52_week_low", "unusual_volume", "most_active", "oversold", "overbought" ], "type": "string", "default": "none", "description": "Market signal, for example top_gainers." }, "max_results": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "description": "Maximum number of stocks to return, for example 20. Up to 100." }, "company_size": { "enum": [ "any", "mega", "large", "mid", "small", "micro" ], "type": "string", "default": "any", "description": "Market value range, for example large ($10B–$200B)." }, "minimum_dividend_yield_percent": { "type": "number", "default": 0, "minimum": 0, "description": "Minimum annual dividend yield as a percentage, for example 2.5." }, "maximum_price_to_earnings_ratio": { "type": "number", "minimum": 0, "description": "Max P/E ratio, for example 25. Omit to include any P/E." } }}Output schema
{ "type": "object", "required": [ "stocks" ], "properties": { "stocks": { "type": "array", "items": { "type": "object", "required": [ "company", "ticker", "sector", "industry", "country", "market_cap_usd", "price_to_earnings_ratio", "price_usd", "change_percent_today", "volume_shares", "page_url" ], "properties": { "sector": { "type": [ "string", "null" ], "description": "Business sector." }, "ticker": { "type": "string", "description": "Stock symbol." }, "company": { "type": "string", "description": "Company name." }, "country": { "type": [ "string", "null" ], "description": "Company country." }, "industry": { "type": [ "string", "null" ], "description": "Industry." }, "page_url": { "type": "string", "description": "Finviz stock page." }, "price_usd": { "type": [ "number", "null" ], "description": "Price in US dollars." }, "volume_shares": { "type": [ "integer", "null" ], "description": "Shares traded." }, "market_cap_usd": { "type": [ "number", "null" ], "description": "Market capitalization in US dollars." }, "change_percent_today": { "type": [ "number", "null" ], "description": "Current-day price change, percent." }, "price_to_earnings_ratio": { "type": [ "number", "null" ], "description": "Price-to-earnings ratio." } }, "additionalProperties": false }, "description": "Matching US stocks." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
finviz.com/screen_stocks- Returns
- company, ticker, sector, industry, country, market cap, P/E, price, today's change, volume, Finviz page
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method finviz.com/screen_stocks with the inputs above.
Ask your agent
- Find large-cap Utilities stocks yielding at least 3.5% with a P/E under 20, sorted by highest dividend yield.
- Which small-cap Healthcare stocks are showing unusual volume today? Give me the top 15 by today's gain.
- On Finviz, pull mega-cap Technology companies ranked by market cap, with ticker, P/E, price and volume.
- Show me oversold mid-cap Energy stocks with P/E below 12 and a dividend of at least 2%.
- Use Finviz to list Financial sector stocks hitting new 52-week highs, sorted by today's biggest gainers, page 2, 50 results.
See more
All Finviz methodsGet a delayed US-listed stock snapshot from its ticker or company name. Analyst labels summarize Finviz's 1-5 mean score; dividend yield uses the estimated dividend when available. Missing metrics return null.
finviz.com/get_stock_snapshotLists recent Form 4 insider trades on Finviz, optionally for one company or ticker and filtered to buys, sales, or both.
finviz.com/list_insider_tradesFinds publicly listed stocks in a country, filtered by sector, US-dollar market cap band and minimum dividend yield, in the requested order. Quotes may be delayed.
tradingview.com/screen_stocksLists Yahoo Finance's top gainers, top losers, most active stocks, or regional trending tickers in Yahoo's order, with price, change, volume and market cap.
finance.yahoo.com/list_market_moversLists MSN Money's current leading stock gainers, losers, or most-active shares in a selected market, in MSN's order. Lists may contain fewer than 50 stocks and prices may be delayed.
msn.com/list_market_moversLooks up a public company by name or ticker on SEC EDGAR and returns its reported annual or quarterly financial figures from XBRL company facts. Quarterly flows are derived from year-to-date totals when no quarterly figure is filed. Unavailable figures are null.
sec.gov/get_company_financialsLists the Fortune 500 for a year. You can filter by industry or sector and by headquarters state. Each company comes with its public financial and company details.
fortune.com/list_fortune_500Ranks public companies worldwide, or by country and industry, by market cap, revenue, earnings, employees or dividend yield. When both a country and an industry are set, the industry ranking order is kept and only companies from that country are shown.
companiesmarketcap.com/list_largest_companies