Stock Screener API

Search financial statements

curl --request POST \
  --url https://api.financialdatasets.ai/financials/search/screener \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "filters": [
    {
      "field": "<string>",
      "value": 123
    }
  ],
  "limit": 10,
  "currency": "USD",
  "as_of": "2023-12-25"
}
'

import requests

url = "https://api.financialdatasets.ai/financials/search/screener"

payload = {
    "filters": [
        {
            "field": "<string>",
            "value": 123
        }
    ],
    "limit": 10,
    "currency": "USD",
    "as_of": "2023-12-25"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filters: [{field: '<string>', value: 123}],
    limit: 10,
    currency: 'USD',
    as_of: '2023-12-25'
  })
};

fetch('https://api.financialdatasets.ai/financials/search/screener', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.financialdatasets.ai/financials/search/screener",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filters' => [
        [
                'field' => '<string>',
                'value' => 123
        ]
    ],
    'limit' => 10,
    'currency' => 'USD',
    'as_of' => '2023-12-25'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.financialdatasets.ai/financials/search/screener"

	payload := strings.NewReader("{\n  \"filters\": [\n    {\n      \"field\": \"<string>\",\n      \"value\": 123\n    }\n  ],\n  \"limit\": 10,\n  \"currency\": \"USD\",\n  \"as_of\": \"2023-12-25\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.financialdatasets.ai/financials/search/screener")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": [\n    {\n      \"field\": \"<string>\",\n      \"value\": 123\n    }\n  ],\n  \"limit\": 10,\n  \"currency\": \"USD\",\n  \"as_of\": \"2023-12-25\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.financialdatasets.ai/financials/search/screener")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": [\n    {\n      \"field\": \"<string>\",\n      \"value\": 123\n    }\n  ],\n  \"limit\": 10,\n  \"currency\": \"USD\",\n  \"as_of\": \"2023-12-25\"\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "ticker": "<string>",
      "report_period": "2023-12-25",
      "currency": "<string>",
      "filing_date": "2023-12-25",
      "sector": "<string>",
      "industry": "<string>"
    }
  ],
  "as_of": "2023-12-25",
  "coverage_start": "2023-12-25"
}

{
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key provided"
}

{
  "error": "Payment Required",
  "message": "This endpoint requires a paid subscription. Please upgrade your plan."
}

{
  "error": "Not Found",
  "message": "Ticker XXXX not found"
}

POST

financials

screener

Search financial statements

curl --request POST \
  --url https://api.financialdatasets.ai/financials/search/screener \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "filters": [
    {
      "field": "<string>",
      "value": 123
    }
  ],
  "limit": 10,
  "currency": "USD",
  "as_of": "2023-12-25"
}
'

import requests

url = "https://api.financialdatasets.ai/financials/search/screener"

payload = {
    "filters": [
        {
            "field": "<string>",
            "value": 123
        }
    ],
    "limit": 10,
    "currency": "USD",
    "as_of": "2023-12-25"
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filters: [{field: '<string>', value: 123}],
    limit: 10,
    currency: 'USD',
    as_of: '2023-12-25'
  })
};

fetch('https://api.financialdatasets.ai/financials/search/screener', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.financialdatasets.ai/financials/search/screener",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filters' => [
        [
                'field' => '<string>',
                'value' => 123
        ]
    ],
    'limit' => 10,
    'currency' => 'USD',
    'as_of' => '2023-12-25'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.financialdatasets.ai/financials/search/screener"

	payload := strings.NewReader("{\n  \"filters\": [\n    {\n      \"field\": \"<string>\",\n      \"value\": 123\n    }\n  ],\n  \"limit\": 10,\n  \"currency\": \"USD\",\n  \"as_of\": \"2023-12-25\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.financialdatasets.ai/financials/search/screener")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": [\n    {\n      \"field\": \"<string>\",\n      \"value\": 123\n    }\n  ],\n  \"limit\": 10,\n  \"currency\": \"USD\",\n  \"as_of\": \"2023-12-25\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.financialdatasets.ai/financials/search/screener")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": [\n    {\n      \"field\": \"<string>\",\n      \"value\": 123\n    }\n  ],\n  \"limit\": 10,\n  \"currency\": \"USD\",\n  \"as_of\": \"2023-12-25\"\n}"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "ticker": "<string>",
      "report_period": "2023-12-25",
      "currency": "<string>",
      "filing_date": "2023-12-25",
      "sector": "<string>",
      "industry": "<string>"
    }
  ],
  "as_of": "2023-12-25",
  "coverage_start": "2023-12-25"
}

{
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key provided"
}

{
  "error": "Payment Required",
  "message": "This endpoint requires a paid subscription. Please upgrade your plan."
}

{
  "error": "Not Found",
  "message": "Ticker XXXX not found"
}

Overview

The Financial Datasets stock screener API returns the stocks that match your filters on financial statement fields, financial metrics, sector, and industry. It covers 17,000+ US tickers and screens the latest reported data, updated within 1 second. With as_of it screens the data that was public on any date since 2010, for backtests without lookahead. Financial statement data is parsed directly from SEC filings (data provenance). You can call it as a REST endpoint with an API key, or from Claude, ChatGPT, Cursor, and other AI apps through the MCP server. Pricing starts at $20. 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 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:

// 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:

// 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, or any date since 2010-03-01 with `as_of`	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.
order_by (object, optional): Sort the matches before the limit applies, for example {"field": "market_cap", "direction": "desc"}. field is any numeric filter field; direction is asc or desc (default desc). Without it, results come back sorted by ticker. The sort field is added to every result row.
as_of (date, optional): Screen as of this date, YYYY-MM-DD. See Point-in-time screening.
currency (string, optional): The currency of the statement values. Defaults to USD.

A company is on the screen while its latest reported period is at most 180 days old. That is the longest legal gap between a period end and the next filing, so a company between quarters stays on the screen and a company that stopped filing drops off. 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)

in works on every field: a list of numbers for a numeric field, a list of strings for sector, industry, and ticker.

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.

# 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",
]

# 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",
]

# 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",
]

# 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",
]

# 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 (Global Industry Classification Standard) classification system.

Point-in-time screening for backtests

Add as_of to screen on the data that was public on that date. For each company, the screener takes the newest filing it had made public on or before as_of and applies your filters to that filing. A report filed after as_of is never used, even when its period ends before as_of. This is the universe a backtest could have picked from on that day, with no lookahead.

// Send JSON Request
{
  "as_of": "2024-01-15",
  "filters": [
    { "field": "market_cap", "operator": "gt", "value": 10000000000 },
    { "field": "revenue", "operator": "gt", "value": 1000000000 }
  ],
  "order_by": { "field": "market_cap", "direction": "desc" },
  "limit": 2
}

// Receive JSON Response
{
  "results": [
    {
      "ticker": "AAPL",
      "filing_date": "2023-11-03",
      "report_period": "2023-09-30",
      "currency": "USD",
      "market_cap": 2676736860720.0,
      "revenue": 383285000000.0,
      "sector": "Information Technology",
      "industry": "Technology Hardware, Storage & Peripherals"
    },
    {
      "ticker": "MSFT",
      "filing_date": "2023-10-24",
      "report_period": "2023-09-30",
      "currency": "USD",
      "market_cap": 2346736830381.75,
      "revenue": 218310000000.0,
      "sector": "Information Technology",
      "industry": "Software"
    }
  ],
  "as_of": "2024-01-15",
  "coverage_start": "2010-03-01"
}

Every row carries filing_date, the day the matched filing became public, and report_period, the period it covers. The response carries as_of and coverage_start, the earliest date you can screen as of.

as_of must be between coverage_start (2010-03-01) and today. A date outside that range returns a 400 that names the earliest date.
stock_price is not available with as_of. Market cap and the price ratios (pe_ratio, pb_ratio, ps_ratio, ev_ebitda_ratio, ev_revenue_ratio) are as computed when the filing was processed, not recomputed at the close of as_of.
The 180-day rule applies to as_of too: a company is on the screen while its latest period on that date is at most 180 days old.

Code Example

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("---")

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("---")

FAQ

Which fields can I screen on?

Income statement, balance sheet, cash flow statement, and financial metrics fields, plus sector and industry. The full list is in Available Filters, or fetch it with GET /financials/search/screener/filters.

How do I screen by sector or industry?

Use sector or industry with the eq or in operator. Values are case-insensitive and follow the GICS classification.

Can I run the screen as of a past date for a backtest?

Yes. Add as_of (YYYY-MM-DD, from 2010-03-01). The screen uses only filings that were public on that date, so a backtest never sees a report filed later. See Point-in-time screening.

Can I sort the results, for example the top 50 by market cap?

Yes. Add order_by, for example {"field": "market_cap", "direction": "desc"} with "limit": 50. The sort runs before the limit, so you get the top rows without fetching the whole universe.

Why did a company disappear from the screen?

Its latest reported period is more than 180 days old, which means it has missed a filing deadline or stopped filing. It returns when its next filing is processed.

Do I enter margins as percentages?

No. Margins and ratios are decimals: a 10% operating margin is 0.10, not 10.

Can an AI agent use this data?

Yes. Claude, ChatGPT, Cursor, and other MCP clients reach it through the Financial Datasets MCP server.

Authorizations

X-API-KEY

string

header

required

API key for authentication.

Body

application/json

filters

object[]

required

An array of filter objects to apply to the search.

Minimum array length: 1

Show child attributes

limit

integer

default:10

The maximum number of results to return.

Required range: x >= 1

currency

string

default:USD

The currency of the statement values to screen. Defaults to USD.

order_by

object

Sort the matches before the limit applies. Without it, results come back sorted by ticker. The sort field is added to every result row.

Show child attributes

as_of

string<date>

Point-in-time screen for backtests: screen on the newest filing each company had made public on or before this date (YYYY-MM-DD). Without it, the screen uses today's latest data. The date must be between coverage_start (2010-03-01) and today. stock_price is not available with as_of.

Response

Successful search response

results

object[]

The companies that match every filter, sorted by ticker, or by order_by when given.

Show child attributes

as_of

string<date>

With as_of only: the date the screen was run as of, echoed back.

coverage_start

string<date>

With as_of only: the earliest date a point-in-time screen can be run for.

Overview

Integrations

Search

Datasets

Guides

Overview

Coverage

Request Body

Available Filters

Point-in-time screening for backtests

Code Example

FAQ

Which fields can I screen on?

How do I screen by sector or industry?

Can I run the screen as of a past date for a backtest?

Can I sort the results, for example the top 50 by market cap?

Why did a company disappear from the screen?

Do I enter margins as percentages?

Can an AI agent use this data?

Authorizations

Body

Response

​Overview

​Coverage

​Request Body

​Available Filters

​Point-in-time screening for backtests

​Code Example

​FAQ

​Which fields can I screen on?

​How do I screen by sector or industry?

​Can I run the screen as of a past date for a backtest?

​Can I sort the results, for example the top 50 by market cap?

​Why did a company disappear from the screen?

​Do I enter margins as percentages?

​Can an AI agent use this data?

Authorizations

Body

Response

Overview

Coverage

Request Body

Available Filters

Point-in-time screening for backtests

Code Example

FAQ

Which fields can I screen on?

How do I screen by sector or industry?

Can I run the screen as of a past date for a backtest?

Can I sort the results, for example the top 50 by market cap?

Why did a company disappear from the screen?

Do I enter margins as percentages?

Can an AI agent use this data?