> ## Documentation Index > Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt > Use this file to discover all available pages before exploring further. # Historical > Get historical financial metrics and ratios for any US stock ticker. Includes P/E, EV/EBITDA, ROE, and 100+ metrics. ### Overview The financial metrics API provides metrics and ratios for a given stock ticker based on the latest and historical fundamentals data from financial statements. Financial metrics include a company's valuation, profitability, efficiency, liquidity, leverage, growth, and per share metrics over the requested period. To get started, please create an account and grab your API key at [financialdatasets.ai](https://financialdatasets.ai). You will use the API key to authenticate your API requests. ### Coverage | Tickers | Years of Coverage | Updated | | ------- | ----------------- | --------------- | | 19,000+ | 30+ years | Within 1 second | ### Available Tickers You can fetch a list of available tickers with a `GET` request to: [https://api.financialdatasets.ai/financial-metrics/tickers/](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 ```python Financial Metrics theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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) ```python Financial Metrics theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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') ``` ## OpenAPI ````yaml GET /financial-metrics openapi: 3.0.1 info: title: Financial Datasets API description: >- Stock market API with real-time and historical financial data for 27,000+ tickers over 30+ years. Financial statements, equity prices, insider trades, SEC filings, and more. version: 1.0.0 license: name: MIT url: https://opensource.org/licenses/MIT contact: name: API Support url: mailto:support@financialdatasets.ai email: support@financialdatasets.ai termsOfService: https://financialdatasets.ai/terms-of-use servers: - url: https://api.financialdatasets.ai/ description: Production server security: - X-API-KEY: [] tags: - name: Financial Statements description: Access to income statements, balance sheets, and cash flow statements - name: Market Data description: Real-time and historical price data - name: Company Information description: Company facts like ticker, name, and description - name: Earnings description: Earnings data and related information - name: News description: Real-time and historical news articles - name: SEC Filings description: SEC filings and regulatory documents - name: Insider Trades description: Insider trading activity and transactions - name: Activist Ownership description: Activist stakes from SEC Schedule 13D filings, in real time - name: Beneficial Ownership description: >- Holders of more than 5% of a company's shares, from SEC Schedules 13D and 13G - name: Insider Ownership description: Insider ownership statements from SEC Forms 3 and 5 - name: Institutional Holdings description: SEC-direct 13F equity holdings of institutional investment managers - name: Index Funds description: >- ETF and index-fund holdings, weights, and the funds that hold a given security - name: Financial Metrics description: Financial ratios, metrics, and key performance indicators - name: Macroeconomics description: Real-time and historical macroeconomic data like interest rates - name: KPIs description: Sector-specific operational KPIs extracted from earnings releases. paths: /financial-metrics: get: tags: - Financial Metrics summary: Get financial metrics description: >- Get financial metrics for a ticker, including valuation, profitability, efficiency, liquidity, leverage, growth, and per share metrics. operationId: getFinancialMetrics parameters: - name: ticker in: query description: The ticker symbol of the company. Required if cik is not provided. required: false schema: type: string - name: cik in: query description: >- The Central Index Key (CIK) of the company. Can be used instead of ticker. required: false schema: type: string - name: period in: query description: The time period for the financial data. required: true schema: type: string enum: - annual - quarterly - ttm - name: limit in: query description: The maximum number of results to return. required: false schema: type: integer - $ref: '#/components/parameters/ReportPeriod' - $ref: '#/components/parameters/ReportPeriodGte' - $ref: '#/components/parameters/ReportPeriodLte' - $ref: '#/components/parameters/ReportPeriodGt' - $ref: '#/components/parameters/ReportPeriodLt' - $ref: '#/components/parameters/FilingDate' - $ref: '#/components/parameters/FilingDateGte' - $ref: '#/components/parameters/FilingDateLte' - $ref: '#/components/parameters/FilingDateGt' - $ref: '#/components/parameters/FilingDateLt' responses: '200': description: The historical financial metrics and ratios for a ticker content: application/json: schema: $ref: '#/components/schemas/FinancialMetricsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' components: parameters: ReportPeriod: name: report_period in: query description: Filter by exact report period date in YYYY-MM-DD format. required: false schema: type: string format: date ReportPeriodGte: name: report_period_gte in: query description: >- Filter by report period greater than or equal to date in YYYY-MM-DD format. required: false schema: type: string format: date ReportPeriodLte: name: report_period_lte in: query description: Filter by report period less than or equal to date in YYYY-MM-DD format. required: false schema: type: string format: date ReportPeriodGt: name: report_period_gt in: query description: Filter by report period greater than date in YYYY-MM-DD format. required: false schema: type: string format: date ReportPeriodLt: name: report_period_lt in: query description: Filter by report period less than date in YYYY-MM-DD format. required: false schema: type: string format: date FilingDate: name: filing_date in: query description: >- Filter by exact SEC filing date in YYYY-MM-DD format. Rows without a known filing date are excluded. required: false schema: type: string format: date FilingDateGte: name: filing_date_gte in: query description: >- Filter by SEC filing date greater than or equal to date in YYYY-MM-DD format. Rows without a known filing date are excluded. required: false schema: type: string format: date FilingDateLte: name: filing_date_lte in: query description: >- Filter by SEC filing date less than or equal to date in YYYY-MM-DD format. Useful for point-in-time queries: returns only data that was publicly filed by the given date. Rows without a known filing date are excluded. required: false schema: type: string format: date FilingDateGt: name: filing_date_gt in: query description: >- Filter by SEC filing date greater than date in YYYY-MM-DD format. Rows without a known filing date are excluded. required: false schema: type: string format: date FilingDateLt: name: filing_date_lt in: query description: >- Filter by SEC filing date less than date in YYYY-MM-DD format. Rows without a known filing date are excluded. required: false schema: type: string format: date schemas: FinancialMetricsResponse: type: object properties: ticker: type: string description: The ticker symbol of the company. report_period: type: string format: date description: The reporting period of the financial metrics. fiscal_period: type: string description: The fiscal period of the financial metrics. period: type: string enum: - quarterly - ttm - annual description: The time period of the financial metrics. currency: type: string description: The currency in which the financial data is reported. accession_number: type: string nullable: true description: The SEC accession number of the filing. filing_url: type: string nullable: true format: uri description: URL to the SEC filing. filing_date: type: string format: date nullable: true description: >- Calendar day SEC accepted the filing, in Eastern Time (the SEC's operating timezone). Calendar-day pair to `filing_datetime`. Null when no dated SEC filing is linked to the row. filing_datetime: type: string format: date-time nullable: true description: >- Sub-day timestamp recording when SEC accepted the filing, in Eastern Time. Sourced from SEC's `acceptanceDateTime` field on the EDGAR submissions API. Pairs with `filing_date` (calendar-day precision of the same event). enterprise_value: type: number description: The total value of the company (market cap + debt - cash). price_to_earnings_ratio: type: number description: Price to earnings ratio. price_to_book_ratio: type: number description: Price to book ratio. price_to_sales_ratio: type: number description: Price to sales ratio. enterprise_value_to_ebitda_ratio: type: number description: Enterprise value to EBITDA ratio. enterprise_value_to_revenue_ratio: type: number description: Enterprise value to revenue ratio. free_cash_flow_yield: type: number description: Free cash flow yield. peg_ratio: type: number description: Price to earnings growth ratio. gross_margin: type: number description: Gross profit as a percentage of revenue. operating_margin: type: number description: Operating income as a percentage of revenue. net_margin: type: number description: Net income as a percentage of revenue. return_on_equity: type: number description: Net income as a percentage of shareholders' equity. return_on_assets: type: number description: Net income as a percentage of total assets. return_on_invested_capital: type: number description: >- Net operating profit after taxes as a percentage of invested capital. asset_turnover: type: number description: Revenue divided by average total assets. inventory_turnover: type: number description: Cost of goods sold divided by average inventory. receivables_turnover: type: number description: Revenue divided by average accounts receivable. days_sales_outstanding: type: number description: Average accounts receivable divided by revenue over the period. operating_cycle: type: number description: Inventory turnover + receivables turnover. working_capital_turnover: type: number description: Revenue divided by average working capital. current_ratio: type: number description: Current assets divided by current liabilities. quick_ratio: type: number description: Quick assets divided by current liabilities. cash_ratio: type: number description: Cash and cash equivalents divided by current liabilities. operating_cash_flow_ratio: type: number description: Operating cash flow divided by current liabilities. debt_to_equity: type: number description: Total debt divided by shareholders' equity. debt_to_assets: type: number description: Total debt divided by total assets. interest_coverage: type: number description: EBIT divided by interest expense. revenue_growth: type: number description: Year-over-year growth in revenue. earnings_growth: type: number description: Year-over-year growth in earnings. book_value_growth: type: number description: Year-over-year growth in book value. earnings_per_share_growth: type: number description: Growth in earnings per share over the period. free_cash_flow_growth: type: number description: Growth in free cash flow over the period. operating_income_growth: type: number description: Growth in operating income over the period. ebitda_growth: type: number description: Growth in EBITDA over the period. payout_ratio: type: number description: Dividends paid as a percentage of net income. earnings_per_share: type: number description: Net income divided by weighted average shares outstanding. book_value_per_share: type: number description: Shareholders' equity divided by shares outstanding. free_cash_flow_per_share: type: number description: Free cash flow divided by shares outstanding. ErrorResponse: type: object properties: error: type: string description: A short error message. message: type: string description: A more detailed error message. responses: BadRequestError: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Bad Request message: Invalid request parameters UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized message: Invalid API key provided PaymentRequiredError: description: The request requires a paid subscription content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Payment Required message: >- This endpoint requires a paid subscription. Please upgrade your plan. NotFoundError: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Not Found message: Ticker XXXX not found securitySchemes: X-API-KEY: type: apiKey name: X-API-KEY description: API key for authentication. in: header ````