POST
/
financials
/
search
Search financial statements
curl --request POST \
  --url https://api.financialdatasets.ai/financials/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "period": "ttm",
  "limit": 100,
  "order_by": "ticker",
  "currency": "USD",
  "historical": false,
  "filters": [
    {
      "field": "<string>",
      "operator": "gt",
      "value": 123
    }
  ]
}'
{
  "search_results": [
    {
      "ticker": "<string>",
      "report_period": "2023-12-25",
      "period": "annual",
      "currency": "<string>"
    }
  ]
}

​
👋 Overview

This endpoint lets you search for companies based on a set of filters that you specify. You can filter by any financial metric that is listed below in the Filters section. For example, you can search for companies with revenue greater than $100 million and capital expenditure less than $10 million and receive the following response: 
{
  "search_results": [
    {
      "ticker": "ORCL",
      "report_period": "2024-08-31",
      "period": "ttm",
      "revenue": 53815000000,
      "capital_expenditure": -7855000000
    },
    {
      "ticker": "PLAY",
      "report_period": "2024-08-06",
      "period": "ttm",
      "revenue": 2211100000,
      "capital_expenditure": -424400000
    }
  ]
}
To get started, please create an account and grab your API key at financialdatasets.ai. You will use the API key to authenticate your API requests. The Financials Search API lets you search for financial data across income statements, balance sheets, and cash flow statements for 16,000+ public companies, going back 30+ years.

​
🚀 Getting Started

There are 3 steps for making a successful API call:
  1. Add your API key to the header of the request as X-API-KEY.
  2. Prepare a JSON body with your search criteria, including period, limit, and filters.
  3. Execute the API request to the /financials/search endpoint using a POST method.
The period can be one of "ttm" (trailing twelve months), "annual", or "quarterly". Note: filters is required. By default, period is "ttm" and limit is 100.

​
🔎 Filters

You can filter the search results by adding one or more filters. You may specify multiple filters to narrow down the search results. We charge $0.01 per 10 filters per search. For example, 5 filters costs $0.01, 15 filters costs $0.02, and so on. Each filter consists of a field, an operator, and a value. The operator must be one of:
  • "eq" (equal to)
  • "gt" (greater than)
  • "gte" (greater than or equal to)
  • "lt" (less than)
  • "lte" (less than or equal to)
The value must be a number like 1000000. The field must be one of the following from the income statement, balance sheet, or cash flow statement: 
# 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",
]

​
💻 Examples

import requests
import json

# Add your API key to the headers
headers = {
    "X-API-KEY": "your_api_key_here",
    "Content-Type": "application/json"
}

# Prepare the request body
body = {
    "period": "ttm",
    "limit": 5,
    "currency": "USD",
    "filters": [
        {
            "field": "revenue", # from income statement
            "operator": "gte",
            "value": 100000000
        },
        {
            "field": "total_debt", # from balance sheet
            "operator": "lte",
            "value": 1
        },
        {
            "field": "capital_expenditure", # from cash flow statement
            "operator": "lt",
            "value": 10000000
        },
    ]
}

# Create the URL
url = 'https://api.financialdatasets.ai/financials/search'

# Make API request
response = requests.post(url, headers=headers, data=json.dumps(body))

# Parse search results from the response
search_results = response.json().get('search_results')

# Print the results
for result in search_results:
    print(f"Ticker: {result['ticker']}")
    print(f"Report Period: {result['report_period']}")
    print(f"Revenue: ${result['revenue']:,.0f}")
    print(f"Total Debt: ${result['total_debt']:,.0f}")
    print(f"Capital Expenditure: ${result['capital_expenditure']:,.0f}")
    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 length: 1
​
period
enum<string>
default:ttm

The time period for the financial data.

Available options:
annual,
quarterly,
ttm
​
limit
integer
default:100

The maximum number of results to return.

Required range: 1 <= x <= 100
​
order_by
enum<string>
default:ticker

The field to order the results by. Use -field to order in descending order.

Available options:
ticker,
-ticker,
report_period,
-report_period
​
currency
enum<string>

The currency of the financial data.

Available options:
USD,
EUR,
GBP,
JPY,
CHF,
AUD,
CAD,
SEK
​
historical
boolean
default:false

Whether to return historical financial data.

Response

Successful search response

​
search_results
object[]