GET
/
financial-metrics
curl --request GET \
  --url https://api.financialdatasets.ai/financial-metrics \
  --header 'X-API-KEY: <api-key>'
{
  "ticker": "<string>",
  "market_cap": 123,
  "enterprise_value": 123,
  "price_to_earnings_ratio": 123,
  "price_to_book_ratio": 123,
  "price_to_sales_ratio": 123,
  "enterprise_value_to_ebitda_ratio": 123,
  "enterprise_value_to_revenue_ratio": 123,
  "free_cash_flow_yield": 123,
  "peg_ratio": 123,
  "gross_margin": 123,
  "operating_margin": 123,
  "net_margin": 123,
  "return_on_equity": 123,
  "return_on_assets": 123,
  "return_on_invested_capital": 123,
  "asset_turnover": 123,
  "inventory_turnover": 123,
  "receivables_turnover": 123,
  "days_sales_outstanding": 123,
  "operating_cycle": 123,
  "working_capital_turnover": 123,
  "current_ratio": 123,
  "quick_ratio": 123,
  "cash_ratio": 123,
  "operating_cash_flow_ratio": 123,
  "debt_to_equity": 123,
  "debt_to_assets": 123,
  "interest_coverage": 123,
  "revenue_growth": 123,
  "earnings_growth": 123,
  "book_value_growth": 123,
  "earnings_per_share_growth": 123,
  "free_cash_flow_growth": 123,
  "operating_income_growth": 123,
  "ebitda_growth": 123,
  "payout_ratio": 123,
  "earnings_per_share": 123,
  "book_value_per_share": 123,
  "free_cash_flow_per_share": 123
}

​
👋 Overview

The historical financial metrics API provides historical financial metrics and ratios for a given stock ticker.

Financial metrics include a company’s valuation, profitability, efficiency, liquidity, leverage, growth, and per share metrics over a specified period.

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.

​
📊 Available Tickers

You can fetch a list of available tickers with a GET request to: https://api.financialdatasets.ai/financial-metrics/tickers/

​
🚀 Getting Started

There are only 3 steps for making a successful API call:

  1. Add your API key to the header of the request as X-API-KEY.
  2. Add query params like ticker to filter the data.
  3. Execute the API request.

​
🔎 Filtering the Data

You can filter the data by ticker, period, limit, and report_period.

Note: ticker and period are required. By default, limit is 4 and report_period is null.

The period parameter can be set to annual, quarterly, or ttm (trailing twelve months). The limit parameter is used to specify the number of periods to return.

The report_period parameter is used to specify the date of the financial metrics. For example, you can include filters like report_period_lte=2024-09-30 and report_period_gte=2024-01-01 to get financial metrics between January 1, 2024 and September 30, 2024.

The available report_period operations are:

  • report_period_lte
  • report_period_lt
  • report_period_gte
  • report_period_gt
  • report_period

​
💻 Example

Financial Metrics
import requests

# add your API key to the headers
headers = {
    "X-API-KEY": "your_api_key_here"
}

# set your query params
ticker = 'NVDA'     # stock ticker
period = 'annual'   # possible values are 'annual', 'quarterly', or 'ttm'
limit = 30          # number of periods to return

# create the URL
url = (
    f'https://api.financialdatasets.ai/financial-metrics'
    f'?ticker={ticker}'
    f'&period={period}'
    f'&limit={limit}'
)

# make API request
response = requests.get(url, headers=headers)

# parse financial_metrics from the response
financial_metrics = response.json().get('financial_metrics')

​
💻 Example (with report_period)

Financial Metrics
import requests

# add your API key to the headers
headers = {
    "X-API-KEY": "your_api_key_here"
}

# set your query params
ticker = 'NVDA'     
period = 'ttm'      
report_period_lte = '2024-01-01' # end date
report_period_gte = '2020-01-01' # start date

# create the URL
url = (
    f'https://api.financialdatasets.ai/financial-metrics'
    f'?ticker={ticker}'
    f'&period={period}'
    f'&report_period_lte={report_period_lte}'
    f'&report_period_gte={report_period_gte}'
)

# make API request
response = requests.get(url, headers=headers)

# parse financial_metrics from the response
financial_metrics = response.json().get('financial_metrics')

Authorizations

​
X-API-KEY
string
header
required

API key for authentication.

Query Parameters

​
ticker
string
required

The ticker symbol of the company.

​
period
enum<string>
required

The time period for the financial data.

Available options:
annual,
quarterly,
ttm
​
limit
integer

The maximum number of results to return.

Response

200
application/json

The historical financial metrics and ratios for a ticker

The response is of type object.