Skip to main content
POST
/
financials
/
search
/
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>",
      "operator": "gt",
      "value": 123
    }
  ],
  "limit": 10
}
'
{
  "search_results": [
    {
      "ticker": "<string>",
      "report_period": "2023-12-25",
      "period": "annual",
      "currency": "<string>"
    }
  ]
}

​
Overview

This endpoint lets you screen for companies that match your investment criteria by filtering on fundamental financial metrics. You can combine multiple conditions—such as revenue thresholds, valuation ratios, profitability margins, and debt levels—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
    }
  ]
}

​
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 to filter on.
  • operator (string): The comparison operator.
  • value (integer or decimal): The value to compare against.
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/metrics. 
# 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",
]
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.

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

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
​
limit
integer
default:10

The maximum number of results to return.

Required range: x >= 1

Response

Successful search response

​
search_results
object[]