Stock Screener API
Last updated:
Filter stocks by P/E ratio, revenue growth, margins, dividend yield, and 1,000+ other fundamental metrics via a single POST endpoint. Combine unlimited conditions using AND/OR logic, select your output columns, and get paginated results refreshed every minute. The API is free to use.
https://data.businessquant.com/screener?page={page}&limit={limit}&api_key={api_key}
How this fits the Business Quant API suite: The screener is the natural starting point for building stock universes. Once you have a filtered set of tickers, enrich each one with the Company Profile API for full identifier and narrative data, drill into Financial Statements for period-level history, or feed the ticker list into the Peers API for competitive benchmarking.
Key Capabilities
The screener is a fundamentals-only engine. It does not expose price-based or chart-pattern technical indicators — every filterable metric derives from financial statements, valuation models, or derived ratios.
1,000+ Fundamental Metrics
Filter on income statement line items, balance sheet positions, cash flow metrics, valuation multiples, profitability ratios, growth rates, leverage, dividends, and more — all from a single API call.
Unlimited Filter Combinations
Combine any number of metric conditions using AND, OR, and parentheses for grouping. Express multi-factor stock screens as naturally as a SQL WHERE clause — there is no cap on complexity.
Column-Level Output Control
Specify preferred_columns to return only the metrics you care about alongside base identifiers (ticker, CIK, name, sector, industry). Avoid bloated responses — fetch exactly what your model or dashboard needs.
Minute-Level Data Refresh
Screener data is updated every minute. Conditions you write today run against near real-time fundamental values — useful for monitoring screens that react to earnings releases, restatements, or ratio threshold crossings.
Schema Discovery via Metadata
Call GET /metadata?table=screener to retrieve the master list of all valid metric names, short labels, datatypes, and statement categories. Use it to populate filter dropdowns, validate user inputs, or drive a query builder UI.
Paginated Results
The response includes total_records and total_pages in the metadata object so you can iterate reliably. Use the page and limit query parameters to page through the full result set in your pipeline.
1. How It Works
The screener is a two-endpoint workflow. The metadata endpoint lets you discover the full set of filterable metrics before writing conditions; the screener endpoint executes your filter and returns matching records.
2. Parameters & Payload
The screener endpoint accepts authentication and pagination parameters in the URL query string, and a JSON body that defines your filtering logic and requested output columns. The conditions string references metric names from the metadata endpoint; the preferred_columns array controls which of those metrics appear in the response.
Query Parameters
| Parameter | Description |
|---|---|
| api_key |
Required
Your unique API key for authentication.
|
| page |
Optional
The page number for pagination. Default is 1.
Format:
page=1 |
| limit |
Optional
The maximum number of records to return per page. Default is 10000.
Format:
limit=500 |
JSON Body (Payload)
| Key | Description |
|---|---|
| conditions |
Required
String
A SQL-like filter string for the screener universe. Supports standard logical operators (AND, OR) and parentheses () for complex grouping. Wrap all metric names in double quotes " " and escape them when inside a JSON string.
Example:
"conditions": "\"P/E Ratio\" < 15 AND (\"sector\" = 'Technology' OR \"sector\" = 'Healthcare')" |
| preferred_columns |
Optional
Array
An array of metric_full strings specifying additional columns to include in the response alongside base identification fields. If omitted, only base identifiers are returned.
Example:
"preferred_columns": ["Revenue (Yr)", "Net Income (Yr)"] |
curl -X POST "https://data.businessquant.com/screener?page=1&limit=50&api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"conditions": "\"Market Capitalization\" > 5000000000 AND \"P/E Ratio\" < 15 AND (\"sector\" = '\'Technology\'' OR \"sector\" = '\'Healthcare\'')",
"preferred_columns": [
"Revenue (Yr)",
"Net Income (Yr)",
"Dividend Yield"
]
}'
{
"metadata": {
"total_records": 438,
"total_pages": 9,
"page": 1,
"limit": 50
},
"data": [
{
"ticker": "AAPL",
"cik": 320193,
"name": "Apple Inc.",
"name_short": "Apple",
"sector": "Technology",
"industry": "Consumer Electronics",
"Market Capitalization": 2850000000000.0,
"P/E Ratio": 18.52,
"Revenue (Yr)": 383285000000.0,
"Net Income (Yr)": 96995000000.0,
"Dividend Yield": "0.53%"
},
{
"ticker": "JNJ",
"cik": 200406,
"name": "Johnson & Johnson",
"name_short": "J&J",
"sector": "Healthcare",
"industry": "Drug Manufacturers",
"Market Capitalization": 375000000000.0,
"P/E Ratio": 10.85,
"Revenue (Yr)": 85159000000.0,
"Net Income (Yr)": 35000000000.0,
"Dividend Yield": "3.05%"
}
]
}
3. Understanding the Syntax
Because conditions is passed as a single string inside a JSON payload, any internal double quotes used to wrap metric names must be escaped with a backslash (\"). Text comparison values — such as sector and industry names — use single quotes. You can compose arbitrarily complex logical structures with AND, OR, and parentheses.
1. Standard Logic (readable form):
AND "P/E Ratio" < 15
AND ("sector" = 'Technology' OR "sector" = 'Healthcare')
2. Final Escaped JSON (Paste directly into Postman Body):
{
"page": 1,
"limit": 50,
"conditions": "\"Market Capitalization\" > 5000000000 AND \"P/E Ratio\" < 15 AND (\"sector\" = 'Technology' OR \"sector\" = 'Healthcare')",
"preferred_columns": [
"Revenue (Yr)",
"Net Income (Yr)",
"Dividend Yield"
]
}
4. Fetch Screener Metadata (Schema Discovery)
Before building conditions or a filter UI, call the metadata endpoint to retrieve the complete, authoritative list of all filterable metric names and their datatypes. The metric_full string from each record is the exact value to use in conditions and preferred_columns.
https://data.businessquant.com/metadata?table=screener&api_key={api_key}
curl -X GET "https://data.businessquant.com/metadata?table=screener&api_key=YOUR_API_KEY"
Understanding the Schema Response
The metadata endpoint acts as a programmatic data dictionary for the screener. Use it to populate filter dropdowns, validate user inputs, or drive a query builder UI before sending a POST request.
| Field | Description |
|---|---|
metric_full |
The exact string to use in your conditions and preferred_columns payload. Must match character-for-character. |
metric_short |
Condensed, UI-friendly display name for filter labels and column headers. |
datatype |
How to format the value — number for raw numeric values, % for percentages. Use this to render comparison inputs correctly in a UI. |
statement |
Financial category the metric belongs to — e.g., Overview, Valuation Ratios, Profitability. Use for grouping in filter UIs. |
[
{
"metric_full": "Market Capitalization",
"metric_short": "Market Cap",
"datatype": "number",
"statement": "Overview"
},
{
"metric_full": "P/E Ratio",
"metric_short": "P/E Ratio",
"datatype": "number",
"statement": "Valuation Ratios"
},
{
"metric_full": "Gross Profit Margin (Yr)",
"metric_short": "Gross Margin (Yr)",
"datatype": "%",
"statement": "Profitability"
},
{
"metric_full": "Return on Equity (Yr)",
"metric_short": "ROE (Yr)",
"datatype": "%",
"statement": "Management Effectiveness"
},
{
"metric_full": "Revenue Growth (YoY)",
"metric_short": "Rev Growth (YoY)",
"datatype": "%",
"statement": "Growth Ratios"
}
]
5. Stock Screening Strategies & Use Cases
Common investment research and quantitative workflows mapped directly to conditions strings and preferred_columns selections.
Value & Quality Screens
Combine valuation constraints (earnings multiples, EV/EBITDA) with quality filters (ROE, operating margins, debt/equity) to surface undervalued names with durable economics. Add dividend yield or payout ratio filters to narrow further.
Growth & Momentum Filters
Isolate high-growth companies using revenue growth (YoY), earnings growth, and reinvestment ratio metrics. Stack multiple growth conditions with AND to require consistent expansion across both top and bottom line.
Dividend & Income Strategies
Build income-oriented screens by filtering on dividend yield thresholds, payout ratios, and free cash flow coverage. Pair with leverage filters to avoid high-yield traps from financially stressed companies.
Factor & Quant Model Inputs
Generate factor baskets — value, quality, low leverage, profitability — by specifying metric conditions that match your factor definitions. Use preferred_columns to export exactly the fields your ranking or optimization model needs.
Portfolio & Watchlist Monitoring
Run the same fundamental conditions on a recurring schedule against your watchlist tickers to detect when names drift out of mandate — earnings multiple expansion, margin deterioration, or leverage threshold breaches.
Interactive Filter UIs
Power a front-end screener by dynamically mapping user-selected filter values to the conditions string and preferred_columns array. Use the metadata endpoint to populate dropdowns and validate inputs client-side before calling the screener.
6. Scope & Limitations
The following constraints define what this endpoint covers. Understanding them upfront prevents integration surprises.
Fundamentals-Only Filtering
Every metric available in conditions derives from financial statements, valuation models, or accounting-based ratios. There are no intraday price patterns, chart-based technical indicators, or volume-derived signals. If your screen depends on RSI, moving averages, or price momentum, this is the wrong endpoint.
No Pre-Built Screens or Strategies
The API exposes raw filtering primitives, not curated watchlists or preset strategies. You define the logic entirely through the conditions string. This gives maximum flexibility but requires that you know which metrics and thresholds define your investment criteria before integrating.
Metric Names Are Case- and Character-Sensitive
The metric_full string must match the value returned by GET /metadata?table=screener exactly — including spaces, parentheses, and capitalization. For example, Revenue (Yr) and revenue (yr) are not interchangeable. Always source metric names directly from the metadata endpoint rather than typing them manually.
Frequently Asked Questions
How many metrics can I filter stocks by with this API?
Over 1,000 fundamental metrics are available, spanning income statement line items, balance sheet positions, cash flow metrics, valuation multiples (P/E, EV/EBITDA, P/B), profitability ratios, growth rates, leverage ratios, and dividend metrics. Call the metadata endpoint to retrieve the full list.
Can I combine multiple filter conditions in one API call?
Yes. The conditions string supports unlimited AND/OR combinations with parentheses for grouping. You can express multi-factor screens — such as P/E < 15 AND Revenue Growth > 10% AND sector = Technology — in a single request.
Is the Stock Screener API free to use?
Yes, the Stock Screener API is free to use. Sign up for an API key and start filtering stocks immediately.
How often is the screener data refreshed?
Screener data is refreshed every minute. Conditions run against near real-time fundamental values, so screens react to earnings releases, restatements, and ratio threshold changes throughout the trading day.
Does the screener support technical indicators like RSI or moving averages?
No. This is a fundamentals-only screener. Every filterable metric derives from financial statements, valuation models, or accounting-based ratios. There are no price-based technical indicators, chart patterns, or volume-derived signals.