> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Stock Screener
> Screen and filter stocks by financial metrics like revenue, net income, P/E ratio, and more.
### Overview
This endpoint lets you screen for companies that match your investment criteria by filtering on fundamental financial metrics and company attributes. You can combine multiple conditions—such as revenue thresholds, valuation ratios, profitability margins, debt levels, and industry/sector classifications—to screen for stocks that fit your strategy. All available metrics are listed in the [Available Filters](#available-filters) section below.
For example, you can search for companies with revenue greater than \$100 million and a P/E ratio less than 20 with the following request body:
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Send JSON Request
{
"filters": [
{
"field": "revenue",
"operator": "gt",
"value": 100000000
},
{
"field": "pe_ratio",
"operator": "lt",
"value": 20
}
]
}
```
And receive the following search results, sorted by ticker:
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Receive JSON Response
{
"results": [
{
"ticker": "AA",
"pe_ratio": 8.37,
"report_period": "2025-09-30",
"currency": "USD",
"revenue": 12868000000.0
},
{
"ticker": "AAL",
"pe_ratio": 14.65,
"report_period": "2025-09-30",
"currency": "USD",
"revenue": 54294000000.0
}
]
}
```
### Coverage
| Tickers | Years of Coverage | Updated |
| ------- | ----------------- | --------------- |
| 17,000+ | Latest | Within 1 second |
### Request Body
A JSON object with the following properties:
* `filters` (array, required): An array of filter objects to apply.
* `limit` (integer, optional): The maximum number of results to return. Defaults to 10.
**Filters**
Each filter object in the `filters` array must contain:
* `field` (string): The financial metric or company attribute to filter on.
* `operator` (string): The comparison operator.
* `value` (integer, decimal, or string): The value to compare against. Use strings for company fields like `sector` and `industry`.
**Operators**
The `operator` must be one of the following:
* `"eq"` (equal to)
* `"gt"` (greater than)
* `"gte"` (greater than or equal to)
* `"lt"` (less than)
* `"lte"` (less than or equal to)
* `"in"` (value is in the provided array)
### Available Filters
You can filter by any of the fields below, which are grouped by their source. You can also fetch these programmatically via `GET /financials/search/screener/filters`.
```python Income Statement theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List of valid filter fields for the income statement
fields = [
"consolidated_income",
"cost_of_revenue",
"dividends_per_common_share",
"earnings_per_share",
"earnings_per_share_diluted",
"ebit",
"ebit_usd",
"earnings_per_share_usd",
"gross_profit",
"income_tax_expense",
"interest_expense",
"net_income",
"net_income_common_stock",
"net_income_common_stock_usd",
"net_income_discontinued_operations",
"net_income_non_controlling_interests",
"operating_expense",
"operating_income",
"preferred_dividends_impact",
"research_and_development",
"revenue",
"revenue_usd",
"selling_general_and_administrative_expenses",
"weighted_average_shares",
"weighted_average_shares_diluted",
]
```
```python Balance Sheet theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List of valid filter fields for the balance sheet
fields = [
"accumulated_other_comprehensive_income",
"cash_and_equivalents",
"cash_and_equivalents_usd",
"current_assets",
"current_debt",
"current_investments",
"current_liabilities",
"deferred_revenue",
"deposit_liabilities",
"goodwill_and_intangible_assets",
"inventory",
"investments",
"non_current_assets",
"non_current_debt",
"non_current_investments",
"non_current_liabilities",
"outstanding_shares",
"property_plant_and_equipment",
"retained_earnings",
"shareholders_equity",
"shareholders_equity_usd",
"tax_assets",
"tax_liabilities",
"total_assets",
"total_debt",
"total_debt_usd",
"total_liabilities",
"trade_and_non_trade_payables",
"trade_and_non_trade_receivables",
]
```
```python Cash Flow Statement theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List of valid filter fields for the cash flow statement
fields = [
"business_acquisitions_and_disposals",
"capital_expenditure",
"change_in_cash_and_equivalents",
"depreciation_and_amortization",
"dividends_and_other_cash_distributions",
"effect_of_exchange_rate_changes",
"investment_acquisitions_and_disposals",
"issuance_or_purchase_of_equity_shares",
"issuance_or_repayment_of_debt_securities",
"net_cash_flow_from_financing",
"net_cash_flow_from_investing",
"net_cash_flow_from_operations",
"share_based_compensation",
"net_income",
"free_cash_flow",
"ending_cash_balance",
"property_plant_and_equipment",
]
```
```python Financial Metrics theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List of valid filter fields for financial metrics
fields = [
"stock_price",
"market_cap",
"enterprise_value",
"pe_ratio",
"pb_ratio",
"ps_ratio",
"ev_ebitda_ratio",
"ev_revenue_ratio",
"free_cash_flow_yield",
"peg_ratio",
"gross_margin",
"operating_margin",
"net_margin",
"return_on_equity",
"return_on_assets",
"return_on_invested_capital",
"asset_turnover",
"inventory_turnover",
"receivables_turnover",
"days_sales_outstanding",
"operating_cycle",
"working_capital_turnover",
"current_ratio",
"quick_ratio",
"cash_ratio",
"operating_cash_flow_ratio",
"debt_to_equity",
"debt_to_assets",
"interest_coverage",
"revenue_growth",
"earnings_growth",
"book_value_growth",
"earnings_per_share_growth",
"free_cash_flow_growth",
"operating_income_growth",
"ebitda_growth",
"dividend_yield",
"payout_ratio",
"earnings_per_share",
"book_value_per_share",
"free_cash_flow_per_share",
]
```
```python Company theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List of valid filter fields for company attributes
# These fields only support "eq" and "in" operators
# Values are case-insensitive (e.g. "health care" matches "Health Care")
fields = [
"industry",
"sector",
]
```
**Margins and ratios** (e.g. `gross_margin`, `operating_margin`, `net_margin`, `revenue_growth`) are stored as decimals, not percentages. For example, a 10% operating margin is `0.10`, not `10`.
**Valuation ratios** like `pe_ratio` can be negative for companies with negative earnings. To screen for a "reasonable" P/E range, use two filters — e.g. `pe_ratio gte 0` and `pe_ratio lte 25`.
**Company fields** (`sector`, `industry`) accept string values and only support the `eq` and `in` operators. Values are case-insensitive — e.g. `"health care"` matches `"Health Care"`. These fields use the [GICS](https://en.wikipedia.org/wiki/Global_Industry_Classification_Standard) (Global Industry Classification Standard) classification system.
### Code Example
```python Filter by Metrics theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
import json
headers = {
"X-API-KEY": "your_api_key_here",
"Content-Type": "application/json"
}
body = {
"limit": 5,
"currency": "USD",
"filters": [
{
"field": "pe_ratio", # from financial metrics
"operator": "lt",
"value": 20
},
{
"field": "revenue", # from income statement
"operator": "gte",
"value": 1000000000
},
{
"field": "total_debt", # from balance sheet
"operator": "lt",
"value": 500000000
},
]
}
url = 'https://api.financialdatasets.ai/financials/search/screener'
response = requests.post(url, headers=headers, data=json.dumps(body))
results = response.json().get('results')
for result in results:
print(f"Ticker: {result['ticker']}")
print(f"P/E Ratio: {result.get('pe_ratio')}")
print(f"Revenue: {result.get('revenue')}")
print(f"Total Debt: {result.get('total_debt')}")
print("---")
```
```python Filter by Sector + Metrics theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
import json
headers = {
"X-API-KEY": "your_api_key_here",
"Content-Type": "application/json"
}
body = {
"limit": 10,
"filters": [
{
"field": "sector", # from company attributes
"operator": "eq",
"value": "Health Care"
},
{
"field": "market_cap", # from financial metrics
"operator": "lt",
"value": 5000000000
},
{
"field": "revenue_growth", # from financial metrics
"operator": "gt",
"value": 0.10
},
]
}
url = 'https://api.financialdatasets.ai/financials/search/screener'
response = requests.post(url, headers=headers, data=json.dumps(body))
results = response.json().get('results')
for result in results:
print(f"Ticker: {result['ticker']}")
print(f"Market Cap: {result.get('market_cap')}")
print(f"Revenue Growth: {result.get('revenue_growth')}")
print("---")
```
## OpenAPI
````yaml POST /financials/search/screener
openapi: 3.0.1
info:
title: Financial Datasets API
description: >-
Stock market API with real-time and historical financial data for 27,000+
tickers over 30+ years. Financial statements, equity prices, insider trades,
SEC filings, and more.
version: 1.0.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
contact:
name: API Support
url: mailto:support@financialdatasets.ai
email: support@financialdatasets.ai
termsOfService: https://financialdatasets.ai/terms-of-use
servers:
- url: https://api.financialdatasets.ai/
description: Production server
security:
- X-API-KEY: []
tags:
- name: Financial Statements
description: Access to income statements, balance sheets, and cash flow statements
- name: Market Data
description: Real-time and historical price data
- name: Company Information
description: Company facts like ticker, name, and description
- name: Earnings
description: Earnings data and related information
- name: News
description: Real-time and historical news articles
- name: SEC Filings
description: SEC filings and regulatory documents
- name: Insider Trades
description: Insider trading activity and transactions
- name: Activist Ownership
description: Activist stakes from SEC Schedule 13D filings, in real time
- name: Beneficial Ownership
description: >-
Holders of more than 5% of a company's shares, from SEC Schedules 13D and
13G
- name: Insider Ownership
description: Insider ownership statements from SEC Forms 3 and 5
- name: Institutional Holdings
description: SEC-direct 13F equity holdings of institutional investment managers
- name: Index Funds
description: >-
ETF and index-fund holdings, weights, and the funds that hold a given
security
- name: Financial Metrics
description: Financial ratios, metrics, and key performance indicators
- name: Macroeconomics
description: Real-time and historical macroeconomic data like interest rates
- name: KPIs
description: Sector-specific operational KPIs extracted from earnings releases.
paths:
/financials/search/screener:
post:
tags:
- Financial Statements
summary: Search financial statements
description: >-
Search for stocks by filtering across financial metrics from income
statements, balance sheets, and cash flow statements.
operationId: searchFinancials
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchFiltersRequest'
responses:
'200':
description: Successful search response
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialsSearchResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'402':
$ref: '#/components/responses/PaymentRequiredError'
'404':
$ref: '#/components/responses/NotFoundError'
components:
schemas:
SearchFiltersRequest:
type: object
required:
- filters
properties:
limit:
type: integer
minimum: 1
default: 10
description: The maximum number of results to return.
filters:
type: array
items:
type: object
required:
- field
- operator
- value
properties:
field:
type: string
description: >-
The criteria to filter on. For financial metric fields, use
'gt', 'lt', 'gte', 'lte', 'eq' operators. For 'ticker' and
'cik' fields, use the 'in' operator to filter against multiple
values.
operator:
type: string
enum:
- gt
- lt
- gte
- lte
- eq
- in
description: >-
The comparison operator. The 'in' operator can only be used
with a field value of 'ticker' or 'cik' and lets you filter
against multiple values.
value:
oneOf:
- type: number
description: >-
The value to compare against for single-value operators
(gt, lt, gte, lte, eq)
- type: array
items:
type: string
description: >-
Array of ticker or cik values to compare against when
using the 'in' operator
minItems: 1
description: An array of filter objects to apply to the search.
FinancialsSearchResponse:
type: object
properties:
search_results:
type: array
items:
type: object
properties:
ticker:
type: string
description: The ticker symbol of the company.
report_period:
type: string
format: date
description: The reporting period of the financial data.
period:
type: string
enum:
- annual
- quarterly
- ttm
description: The time period of the financial data.
currency:
type: string
description: The currency of the financial data.
additionalProperties:
type: string
description: Additional financial metrics based on the search criteria.
ErrorResponse:
type: object
properties:
error:
type: string
description: A short error message.
message:
type: string
description: A more detailed error message.
responses:
BadRequestError:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
message: Invalid request parameters
UnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Unauthorized
message: Invalid API key provided
PaymentRequiredError:
description: The request requires a paid subscription
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment Required
message: >-
This endpoint requires a paid subscription. Please upgrade your
plan.
NotFoundError:
description: The specified resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Not Found
message: Ticker XXXX not found
securitySchemes:
X-API-KEY:
type: apiKey
name: X-API-KEY
description: API key for authentication.
in: header
````