Stock Screener - Financial Datasets

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
}
'

import requests

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

payload = {
    "filters": [
        {
            "field": "<string>",
            "value": 123
        }
    ],
    "limit": 10
}
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})
};

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
  ]),
  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}")

	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}")
  .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}"

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

{
  "search_results": [
    {
      "ticker": "<string>",
      "report_period": "2023-12-25",
      "currency": "<string>"
    }
  ]
}

{
  "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
}
'

import requests

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

payload = {
    "filters": [
        {
            "field": "<string>",
            "value": 123
        }
    ],
    "limit": 10
}
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})
};

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
  ]),
  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}")

	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}")
  .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}"

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

{
  "search_results": [
    {
      "ticker": "<string>",
      "report_period": "2023-12-25",
      "currency": "<string>"
    }
  ]
}

{
  "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

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 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	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.

# 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.

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

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

Response

Successful search response

search_results

object[]

Show child attributes

Non-GAAP Metrics Line Items

​Overview

​Coverage

​Request Body

​Available Filters

​Code Example