Financial Datasets

https://docs.financialdatasets.ai/
Admin
Financial Datasets is a developer-friendly REST API providing premium stock market and...
Tokens:98,397
Snippets:544
Trust Score:6.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install MCP Python SDK

Source: https://docs.financialdatasets.ai/mcp-server

Install the necessary Python SDK for integrating with the MCP server in your scripts or custom applications.

```bash
pip install mcp
```

--------------------------------

### Python MCP Client Session Example

Source: https://docs.financialdatasets.ai/mcp-server

Example of establishing an authenticated connection to the MCP server using the Python SDK and calling a tool. Requires an API key and server URL.

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

API_KEY = "your-api-key"
SERVER_URL = "https://mcp.financialdatasets.ai/api"

async def main():
    # Open an authenticated connection to the MCP server
    async with streamablehttp_client(
        SERVER_URL,
        headers={"X-API-KEY": API_KEY},
    ) as streams:
        read_stream, write_stream, _ = streams

        # Start an MCP session
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # Call any tool from the MCP Tools list
            result = await session.call_tool(
                "get_stock_price",
                {"ticker": "AAPL"},
            )
            print(result.content)

asyncio.run(main())

```

--------------------------------

### Example API Response for Line Items Search

Source: https://docs.financialdatasets.ai/api/financials/search-line-items

This JSON shows an example of the response structure when searching for 'net_income' and 'total_debt' for NVDA and AAPL.

```json
{
  "search_results": [
    {
      "ticker": "NVDA",
      "report_period": "2024-07-28",
      "period": "ttm",
      "net_income": 53008000000,
      "total_debt": 9765000000
    },
    {
      "ticker": "AAPL",
      "report_period": "2024-06-29",
      "period": "ttm",
      "net_income": 101956000000,
      "total_debt": 101304000000
    }
  ]
}
```

--------------------------------

### Fetch KPI Metrics for a Ticker

Source: https://docs.financialdatasets.ai/api/kpi/metrics

Use this Python script to make a GET request to the KPI Metrics API. Ensure your API key is included in the headers. This example fetches data for the ticker 'DAL'.

```python
import requests

headers = {
    "X-API-KEY": "your_api_key_here"
}

ticker = "DAL"
url = f"https://api.financialdatasets.ai/kpi/metrics?ticker={ticker}"

response = requests.get(url, headers=headers)
data = response.json()
kpi_metrics = data["kpi_metrics"]
```

--------------------------------

### Get Insider Trades with Filing Date Filter

Source: https://docs.financialdatasets.ai/api/insider-trades/insider-trades

This example demonstrates how to retrieve insider trades for a specific ticker, filtered by a date range for the filing date. It includes setting up the API key, defining query parameters, constructing the URL, making the request, and parsing the response.

```APIDOC
## GET /insider-trades

### Description
Retrieves a list of insider trades, optionally filtered by ticker symbol and filing date.

### Method
GET

### Endpoint
/insider-trades

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g., 'NVDA').
- **filing_date_lte** (string) - Optional - The end date for filtering trades by filing date (YYYY-MM-DD).
- **filing_date_gte** (string) - Optional - The start date for filtering trades by filing date (YYYY-MM-DD).

### Request Example
```python
import requests

headers = {
    "X-API-KEY": "your_api_key_here"
}

ticker = 'NVDA'
filing_date_lte = '2024-01-01'
filing_date_gte = '2020-01-01'

url = (
    f'https://api.financialdatasets.ai/insider-trades'
    f'?ticker={ticker}'
    f'&filing_date_lte={filing_date_lte}'
    f'&filing_date_gte={filing_date_gte}'
)

response = requests.get(url, headers=headers)
insider_trades = response.json().get('insider_trades')
```

### Response
#### Success Response (200)
- **insider_trades** (array) - A list of insider trade objects.

#### Response Example
```json
{
  "insider_trades": [
    {
      "filing_date": "2023-12-15",
      "transaction_date": "2023-12-10",
      "transaction_type": "Purchase",
      "shares": 1000,
      "price": 180.50,
      "owner_name": "John Doe",
      "owner_relation": "Director"
    }
  ]
}
```
```

--------------------------------

### Fetch Daily Stock Prices

Source: https://docs.financialdatasets.ai/guides/get-stock-prices-python

Use the Prices API to pull end-of-day prices for a specified ticker, interval, start date, and end date. The response includes a list of prices, each with a timestamp and OHLCV data. Only the first 5 entries are printed in this example.

```python
import requests

headers = {
    "X-API-KEY": "your_api_key_here"
}

ticker = "AAPL"
interval = "day"  # options: day, week, month, year
start_date = "2024-01-01"
end_date = "2024-12-31"

url = (
    f"https://api.financialdatasets.ai/prices/"
    f"?ticker={ticker}"
    f"&interval={interval}"
    f"&start_date={start_date}"
    f"&end_date={end_date}"
)

response = requests.get(url, headers=headers)
prices = response.json().get("prices")

for price in prices[:5]:
    print(f"{price['time']}: Open={price['open']}, Close={price['close']}")
```

--------------------------------

### Example API Response

Source: https://docs.financialdatasets.ai/api/prices/historical

This is an example of the JSON response structure you can expect when successfully querying the Historical Prices API. It includes OHLCV data and the timestamp for each period.

```json
{
    "prices": [
        {
            "ticker": "AAPL",
            "open": 243.85,
            "close": 243.36,
            "high": 244.15,
            "low": 241.91,
            "volume": 40230800,
            "time": "2025-01-02"
        },
        {
            "ticker": "AAPL",
            "open": 243.36,
            "close": 245.00,
            "high": 245.55,
            "low": 242.80,
            "volume": 38420500,
            "time": "2025-01-03"
        },
        ...
    ]
}
```

--------------------------------

### Get Market Snapshot

Source: https://docs.financialdatasets.ai/api/prices/market-snapshot

Fetches the real-time price snapshot for the entire market. This endpoint requires an active subscription and authentication.

```APIDOC
## GET /prices/snapshot/market

### Description
Get the real-time price snapshot for the entire market. Requires an active subscription.

### Method
GET

### Endpoint
/prices/snapshot/market

### Parameters

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **snapshots** (array) - An array of price snapshots.
  - **price** (number) - The current price of the stock.
  - **ticker** (string) - The ticker symbol.
  - **day_change** (number) - The price change since the previous trading day's close.
  - **day_change_percent** (number) - The percentage price change since the previous trading day's close.
  - **time** (string) - The timestamp of the price snapshot in human-readable format in UTC.
  - **time_milliseconds** (number) - The timestamp of the price snapshot in milliseconds since epoch.

#### Response Example
```json
{
  "snapshots": [
    {
      "price": 150.75,
      "ticker": "AAPL",
      "day_change": 1.25,
      "day_change_percent": 0.83,
      "time": "2023-10-27T10:00:00Z",
      "time_milliseconds": 1698397200000
    },
    {
      "price": 175.50,
      "ticker": "MSFT",
      "day_change": -0.50,
      "day_change_percent": -0.28,
      "time": "2023-10-27T10:00:00Z",
      "time_milliseconds": 1698397200000
    }
  ]
}
```

#### Error Response (401)
- **error** (string) - A short error message.
- **message** (string) - A more detailed error message.

#### Error Response (402)
- **error** (string) - A short error message.
- **message** (string) - A more detailed error message.

#### Error Response (404)
- **error** (string) - A short error message.
- **message** (string) - A more detailed error message.
```

--------------------------------

### Get Key Performance Indicators (KPIs)

Source: https://docs.financialdatasets.ai/llms.txt

Retrieve operational key performance indicators (KPIs) from earnings releases.

```APIDOC
## Get Key Performance Indicators (KPIs)

### Description
Get operational key performance indicators from earnings releases.

### Method
GET

### Endpoint
/api/kpi/metrics

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol of the company.
```

--------------------------------

### Get Financial Metrics Snapshot

Source: https://docs.financialdatasets.ai/llms.txt

Obtain a real-time snapshot of current financial metrics and valuation ratios for any US stock ticker.

```APIDOC
## Get Financial Metrics Snapshot

### Description
Get a real-time snapshot of current financial metrics and valuation ratios for any US stock ticker.

### Method
GET

### Endpoint
/api/financial-metrics/snapshot

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol of the company.
```

--------------------------------

### Get Price Snapshot

Source: https://docs.financialdatasets.ai/api/prices/snapshot

Fetches the real-time price snapshot for a stock, including current price, day change, and day change percentage.

```APIDOC
## GET /prices/snapshot

### Description
Get the real-time price snapshot for a stock, including the current price, day change, and day change percent.

### Method
GET

### Endpoint
/prices/snapshot

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g. AAPL, MSFT).

### Response
#### Success Response (200)
- **snapshot** (object) - Contains the price snapshot details.
  - **price** (number) - The current price of the stock.
  - **ticker** (string) - The ticker symbol.
  - **day_change** (number) - The price change since the previous trading day's close.
  - **day_change_percent** (number) - The percentage price change since the previous trading day's close.
  - **time** (string) - The timestamp of the price snapshot in human-readable format in UTC.
  - **time_milliseconds** (number) - The timestamp of the price snapshot in milliseconds since epoch.

#### Response Example
```json
{
  "snapshot": {
    "price": 170.50,
    "ticker": "AAPL",
    "day_change": 1.25,
    "day_change_percent": 0.74,
    "time": "2023-10-27T10:00:00Z",
    "time_milliseconds": 1698397200000
  }
}
```

#### Error Response (400)
- **error** (string) - A short error message.
- **message** (string) - A more detailed error message.

#### Error Response Example
```json
{
  "error": "Bad Request",
  "message": "Invalid request parameters"
}
```

#### Error Response (401)
- **error** (string) - A short error message.
- **message** (string) - A more detailed error message.

#### Error Response Example
```json
{
  "error": "Unauthorized",
  "message": "Invalid API key provided"
}
```

#### Error Response (402)
- **error** (string) - A short error message.
- **message** (string) - A more detailed error message.

#### Error Response Example
```json
{
  "error": "Payment Required",
  "message": "This endpoint requires a paid subscription. Please upgrade your plan."
}
```

#### Error Response (404)
- **error** (string) - A short error message.
- **message** (string) - A more detailed error message.

#### Error Response Example
```json
{
  "error": "Not Found",
  "message": "The specified resource was not found"
}
```
```

--------------------------------

### Get Historical Interest Rates

Source: https://docs.financialdatasets.ai/api/macro/interest-rates/historical

Fetches historical interest rate data for a specified central bank. You can filter the results by providing a start and end date.

```APIDOC
## GET /macro/interest-rates

### Description
Historical interest rates for all major central banks in the world.

### Method
GET

### Endpoint
/macro/interest-rates

### Parameters
#### Query Parameters
- **bank** (string) - Required - The bank whose interest rates to return. Use the /macro/interest-rates/banks endpoint to get a list of available banks.
- **start_date** (string) - Optional - The start date of the interest rates to return in YYYY-MM-DD format.
- **end_date** (string) - Optional - The end date of the interest rates to return in YYYY-MM-DD format.

### Responses
#### Success Response (200)
- **interest_rates** (array) - An array of interest rate objects.
  - **bank** (string) - The symbol of the central bank.
  - **name** (string) - The name of the central bank.
  - **rate** (number) - The interest rate of the central bank.
  - **date** (string) - The date of the interest rate in YYYY-MM-DD format.

#### Error Responses
- **400** - Bad Request: Invalid request parameters.
- **401** - Unauthorized: Invalid API key provided.
- **402** - Payment Required: This endpoint requires a paid subscription.
- **404** - Not Found: The requested resource was not found.
```

--------------------------------

### Get Specific Filing Items

Source: https://docs.financialdatasets.ai/llms.txt

Retrieve specific sections and items from SEC filings. Examples include 'Item 1A Risk Factors' or 'Item 7 MD&A'.

```APIDOC
## Get Specific Filing Items

### Description
Get specific sections and items from SEC filings, like Item 1A Risk Factors or Item 7 MD&A.

### Method
GET

### Endpoint
/api/filings/items

### Parameters
#### Query Parameters
- **filing_type** (string) - Required - The type of filing (e.g., 10-K, 10-Q).
- **item_number** (string) - Required - The specific item number to retrieve (e.g., '1A', '7').
```

--------------------------------

### Set Up Authentication Headers

Source: https://docs.financialdatasets.ai/guides/get-stock-prices-python

All API requests require your API key in the 'X-API-KEY' header. Ensure you replace 'your_api_key_here' with your actual key.

```python
import requests

headers = {
    "X-API-KEY": "your_api_key_here"
}
```

--------------------------------

### Filter by Metrics

Source: https://docs.financialdatasets.ai/api/financials/search-screener

This example demonstrates how to filter companies based on financial metrics such as P/E ratio, revenue, and total debt. It retrieves the top 5 results in USD currency.

```APIDOC
## POST /financials/search/screener

### Description
Searches and filters financial data based on specified metrics.

### Method
POST

### Endpoint
https://api.financialdatasets.ai/financials/search/screener

### Parameters
#### Request Body
- **limit** (integer) - Optional - The maximum number of results to return.
- **currency** (string) - Optional - The currency for the financial data (e.g., "USD").
- **filters** (array) - Required - A list of filter conditions.
  - **field** (string) - Required - The financial field to filter on (e.g., "pe_ratio", "revenue", "total_debt").
  - **operator** (string) - Required - The comparison operator (e.g., "lt", "gte", "eq", "gt").
  - **value** (number or string) - Required - The value to compare against.

### Request Example
```json
{
  "limit": 5,
  "currency": "USD",
  "filters": [
    {
      "field": "pe_ratio",
      "operator": "lt",
      "value": 20
    },
    {
      "field": "revenue",
      "operator": "gte",
      "value": 1000000000
    },
    {
      "field": "total_debt",
      "operator": "lt",
      "value": 500000000
    }
  ]
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of matching companies.
  - **ticker** (string) - The stock ticker symbol.
  - **pe_ratio** (number) - The Price-to-Earnings ratio.
  - **revenue** (number) - The company's revenue.
  - **total_debt** (number) - The company's total debt.

#### Response Example
```json
{
  "results": [
    {
      "ticker": "AAPL",
      "pe_ratio": 25.5,
      "revenue": 394000000000,
      "total_debt": 120000000000
    }
  ]
}
```
```

--------------------------------

### Filter Financials by Sector and Metrics

Source: https://docs.financialdatasets.ai/api/financials/search-screener

This example demonstrates filtering companies by both their sector and specific financial metrics such as market capitalization and revenue growth. Remember to insert your API key.

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

--------------------------------

### Filter by Sector + Metrics

Source: https://docs.financialdatasets.ai/api/financials/search-screener

This example shows how to filter companies by both sector and financial metrics, such as market capitalization and revenue growth. It retrieves the top 10 results.

```APIDOC
## POST /financials/search/screener

### Description
Searches and filters financial data based on specified sectors and metrics.

### Method
POST

### Endpoint
https://api.financialdatasets.ai/financials/search/screener

### Parameters
#### Request Body
- **limit** (integer) - Optional - The maximum number of results to return.
- **filters** (array) - Required - A list of filter conditions.
  - **field** (string) - Required - The field to filter on (e.g., "sector", "market_cap", "revenue_growth").
  - **operator** (string) - Required - The comparison operator (e.g., "eq", "lt", "gt").
  - **value** (string or number) - Required - The value to compare against.

### Request Example
```json
{
  "limit": 10,
  "filters": [
    {
      "field": "sector",
      "operator": "eq",
      "value": "Health Care"
    },
    {
      "field": "market_cap",
      "operator": "lt",
      "value": 5000000000
    },
    {
      "field": "revenue_growth",
      "operator": "gt",
      "value": 0.10
    }
  ]
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of matching companies.
  - **ticker** (string) - The stock ticker symbol.
  - **market_cap** (number) - The company's market capitalization.
  - **revenue_growth** (number) - The company's revenue growth rate.

#### Response Example
```json
{
  "results": [
    {
      "ticker": "JNJ",
      "market_cap": 450000000000,
      "revenue_growth": 0.05
    }
  ]
}
```
```

--------------------------------

### Fetch Historical Financial Metrics with Report Period

Source: https://docs.financialdatasets.ai/api/financial-metrics/historical

This example demonstrates how to filter historical financial metrics by a specific date range using `report_period_lte` and `report_period_gte`. This is useful for analyzing metrics within a defined historical window.

```python
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')
```

--------------------------------

### 503 Service Unavailable Response Example

Source: https://docs.financialdatasets.ai/api/filings/items

This is an example of a 503 Service Unavailable response when a filing is being processed. It includes the Retry-After header and a JSON body with details.

```http
HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json

{
  "error": "Filing parse in progress",
  "message": "We are processing this filing. Please retry in ~30 seconds.",
  "accession_number": "0001277902-25-000182",
  "retry_after_seconds": 30
}
```

--------------------------------

### Stock Screener Request

Source: https://docs.financialdatasets.ai/api/financials/search-screener

This example demonstrates how to construct a request to screen for companies with revenue greater than $100 million and a P/E ratio less than 20.

```APIDOC
## POST /financials/search-screener

### Description
Screens for companies based on specified financial metrics and attributes.

### Method
POST

### Endpoint
/financials/search-screener

### Parameters
#### Request Body
- **filters** (array, required) - An array of filter objects to apply. Each filter object must contain:
  - **field** (string) - The financial metric or company attribute to filter on.
  - **operator** (string) - The comparison operator. Must be one of: "eq", "gt", "gte", "lt", "lte", "in".
  - **value** (integer, decimal, or string) - The value to compare against. Use strings for company fields like `sector` and `industry`.
- **limit** (integer, optional) - The maximum number of results to return. Defaults to 10.

### Request Example
```json
{
  "filters": [
    {
      "field": "revenue",
      "operator": "gt",
      "value": 100000000
    },
    {
      "field": "pe_ratio",
      "operator": "lt",
      "value": 20
    }
  ],
  "limit": 50
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of matching company objects.
  - **ticker** (string) - The stock ticker symbol.
  - **pe_ratio** (decimal) - The price-to-earnings ratio.
  - **report_period** (string) - The reporting period for the financial data.
  - **currency** (string) - The currency of the financial metrics.
  - **revenue** (decimal) - The company's revenue.

#### Response Example
```json
{
  "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
    }
  ]
}
```
```

--------------------------------

### Get News Articles

Source: https://docs.financialdatasets.ai/api/news/company

Fetches recent news articles. You can filter by company ticker or get general market news. The number of results can be limited.

```APIDOC
## GET /news

### Description
Get recent news articles for a specific company or the broad market. Pass a ticker for company-specific news, or omit the ticker for general market news. Articles are sourced from RSS feeds of publishers like The Motley Fool, Investing.com, Reuters, and more.

### Method
GET

### Endpoint
/news

### Parameters
#### Query Parameters
- **ticker** (string) - Optional - The ticker symbol of the company. Omit for broad market news.
- **limit** (integer) - Optional - The maximum number of news articles to return (default: 5, max: 10).

### Response
#### Success Response (200)
- **news** (array) - An array of news article objects.
  - **ticker** (string) - The ticker symbol.
  - **title** (string) - The title of the news article.
  - **source** (string) - The source of the news article.
  - **date** (string) - The date the news article was published.
  - **url** (string) - The URL of the news article.

#### Response Example
{
  "news": [
    {
      "ticker": "AAPL",
      "title": "Apple Announces New Product Lineup",
      "source": "Reuters",
      "date": "2023-10-27T10:00:00Z",
      "url": "https://www.reuters.com/article/apple-new-products"
    }
  ]
}

#### Error Responses
- **400** - Bad Request: Invalid request parameters.
- **401** - Unauthorized: Invalid API key provided.
- **402** - Payment Required: This endpoint requires a paid subscription.
- **404** - Not Found: The requested resource was not found.
```

--------------------------------

### Example KPI Guidance Response

Source: https://docs.financialdatasets.ai/api/kpi/guidance

This JSON structure represents a typical response from the KPI Guidance API, detailing financial guidance for a specific ticker and metric.

```json
{
  "kpi_guidance": [
    {
      "ticker": "DAL",
      "metric_name": "Operating Margin",
      "unit": "%",
      "period": "Q2 2026",
      "period_type": "quarterly",
      "low": 6.0,
      "high": 8.0,
      "change_direction": "initiated",
      "source_text": "Operating margin guidance of 6-8%",
      "source_url": "https://www.sec.gov/Archives/..."
    },
    {
      "ticker": "DAL",
      "metric_name": "Earnings Per Share",
      "unit": "dollars",
      "period": "Q2 2026",
      "period_type": "quarterly",
      "low": 1.0,
      "high": 1.5,
      "change_direction": "initiated",
      "source_text": "Earnings per share of $1.00-$1.50",
      "source_url": "https://www.sec.gov/Archives/..."
    }
  ]
}
```

--------------------------------

### Configure Cursor MCP Server

Source: https://docs.financialdatasets.ai/mcp-server

Add the Financial Datasets MCP server configuration to your Cursor client by editing the `~/.cursor/mcp.json` file. Restart Cursor after saving.

```json
{
  "mcpServers": {
    "financial-datasets": {
      "url": "https://mcp.financialdatasets.ai/"
    }
  }
}
```

--------------------------------

### Error Handling

Source: https://docs.financialdatasets.ai/api/earnings/earnings

Example of a common error message returned by the API.

```APIDOC
## Error Handling

### Description
Indicates that a requested ticker symbol was not found.

### Response Example
{
  "message": "Ticker XXXX not found"
}
```

--------------------------------

### List Connected MCP Servers in Claude Code

Source: https://docs.financialdatasets.ai/mcp-server

Verify the connection to the Financial Datasets MCP server by listing all connected servers in Claude Code.

```bash
claude mcp list
```

--------------------------------

### Get Guidance Data

Source: https://docs.financialdatasets.ai/llms.txt

Retrieve forward guidance information provided in earnings releases.

```APIDOC
## Get Guidance Data

### Description
Get forward guidance from earnings releases.

### Method
GET

### Endpoint
/api/kpi/guidance

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol of the company.
```

--------------------------------

### Filter Filings by Multiple Types

Source: https://docs.financialdatasets.ai/api/filings/ticker

This example demonstrates how to filter SEC filings by multiple filing types for a given ticker. Repeat the 'filing_type' parameter for each desired type.

```python
import requests

headers = {"X-API-KEY": "your_api_key_here"}
url = "https://api.financialdatasets.ai/filings"
params = [
    ("ticker", "AAPL"),
    ("filing_type", "10-Q"),
    ("filing_type", "10-K"),
]

response = requests.get(url, headers=headers, params=params)
filings = response.json().get("filings")
```

--------------------------------

### Get Available Tickers

Source: https://docs.financialdatasets.ai/api/financials/cash-flow-statement-segments

Retrieve a list of all available stock tickers supported by the API.

```APIDOC
## GET /financials/cash-flow-statements/segments/tickers/

### Description
Fetches a list of all stock tickers for which cash flow statement segment data is available.

### Method
GET

### Endpoint
/financials/cash-flow-statements/segments/tickers/

### Parameters
This endpoint does not require any parameters.

### Response
#### Success Response (200)
- **tickers** (array) - A list of available stock ticker symbols.

### Response Example
```json
{
  "tickers": ["AAPL", "MSFT", "GOOGL", ...]
}
```
```

--------------------------------

### Fetch All Financial Statements in One Call with Python

Source: https://docs.financialdatasets.ai/guides/analyze-financial-statements-python

Consolidate requests by fetching income statements, balance sheets, and cash flow statements simultaneously using the unified `/financials` endpoint.

```python
url = (
    f"https://api.financialdatasets.ai/financials"
    f"?ticker={ticker}"
    f"&period={period}"
    f"&limit={limit}"
)

response = requests.get(url, headers=headers)
data = response.json()

income_statements = data.get("income_statements")
balance_sheets = data.get("balance_sheets")
cash_flow_statements = data.get("cash_flow_statements")
```

--------------------------------

### Get Price Snapshot

Source: https://docs.financialdatasets.ai/api/prices/snapshot

Retrieve the latest real-time stock price snapshot for a specified ticker.

```APIDOC
## GET /prices/snapshot

### Description
Fetches the latest real-time stock price snapshot for a given US ticker.

### Method
GET

### Endpoint
https://api.financialdatasets.ai/prices/snapshot

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g., AAPL).

### Request Example
```python
import requests

headers = {
    "X-API-KEY": "your_api_key_here"
}

ticker = 'AAPL'

url = (
    f'https://api.financialdatasets.ai/prices/snapshot'
    f'?ticker={ticker}'
)

response = requests.get(url, headers=headers)
snapshot = response.json().get('snapshot')
```

### Response
#### Success Response (200)
- **snapshot** (object) - Contains the price data including open, high, low, and close.

#### Response Example
```json
{
  "snapshot": {
    "open": 170.34,
    "high": 171.00,
    "low": 169.50,
    "close": 170.50
  }
}
```
```

--------------------------------

### Get Non-GAAP Metrics

Source: https://docs.financialdatasets.ai/llms.txt

Retrieve non-GAAP financial metrics along with their GAAP reconciliation context.

```APIDOC
## Get Non-GAAP Metrics

### Description
Get non-GAAP financial metrics with GAAP reconciliation context.

### Method
GET

### Endpoint
/api/kpi/non-gaap

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol of the company.
```

--------------------------------

### Financials Search API Request Example

Source: https://docs.financialdatasets.ai/api/financials/search-line-items

This Python script demonstrates how to make a POST request to the Financials Search API to retrieve specific line items for given tickers. Ensure you replace 'your_api_key_here' with your actual API key.

```python
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",
  "tickers": ["NVDA", "AAPL"],
  "limit": 1,
  "line_items": [
    "net_income",
    "total_debt"
  ]
}

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

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

# Parse search results, which are ordered by report period, newest to oldest
search_results = response.json().get('search_results')
```

--------------------------------

### List Available Insiders

Source: https://docs.financialdatasets.ai/api/insider-trades/insider-trades

Get a list of insider names associated with a specific stock ticker.

```APIDOC
## List Available Insiders

### Description
Retrieves a list of insider names (e.g., officers, directors) associated with a given stock ticker.

### Method
GET

### Endpoint
https://api.financialdatasets.ai/insider-trades/names/

### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g., AAPL).
```

--------------------------------

### Fetch KPI Guidance Data

Source: https://docs.financialdatasets.ai/api/kpi/guidance

Use this Python snippet to make a GET request to the KPI Guidance API. Ensure your API key is included in the headers and the 'ticker' query parameter is set.

```python
import requests

headers = {
    "X-API-KEY": "your_api_key_here"
}

ticker = "DAL"
url = f"https://api.financialdatasets.ai/kpi/guidance?ticker={ticker}"

response = requests.get(url, headers=headers)
data = response.json()
kpi_guidance = data["kpi_guidance"]
```

--------------------------------

### Get Available Tickers

Source: https://docs.financialdatasets.ai/api/earnings/earnings

Retrieve a list of available stock tickers for which earnings data can be fetched.

```APIDOC
## GET /earnings/tickers/

### Description
Fetches a list of available tickers for which earnings data can be retrieved.

### Method
GET

### Endpoint
/earnings/tickers/

### Parameters
None

### Response
#### Success Response (200)
- **tickers** (array) - A list of available ticker symbols.

### Response Example
```json
{
  "tickers": [
    "AAPL",
    "MSFT",
    "NVDA",
    "TSLA",
    "GOOGL",
    "AMZN"
  ]
}
```
```

--------------------------------

### Get Financial Metrics Snapshot

Source: https://docs.financialdatasets.ai/api/financial-metrics/snapshot

Retrieve a snapshot of financial metrics for a given stock ticker.

```APIDOC
## GET /financial-metrics/snapshot

### Description
Fetches a real-time snapshot of current financial metrics and valuation ratios for a specified US stock ticker.

### Method
GET

### Endpoint
/financial-metrics/snapshot

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol for which to retrieve data.

### Request Example
```python
import requests

headers = {
    "X-API-KEY": "your_api_key_here"
}

ticker = 'AAPL'

url = (
    f'https://api.financialdatasets.ai/financial-metrics/snapshot'
    f'?ticker={ticker}'
)

response = requests.get(url, headers=headers)
snapshot = response.json().get('snapshot')
```

### Response
#### Success Response (200)
- **snapshot** (object) - Contains the financial metrics and valuation ratios for the requested ticker.

#### Response Example
```json
{
  "snapshot": {
    "ticker": "AAPL",
    "metrics": { ... }
  }
}
```
```

--------------------------------

### Financial Metrics Snapshot

Source: https://docs.financialdatasets.ai/api/financial-metrics/snapshot

This endpoint returns a comprehensive set of financial metrics, including profitability ratios, turnover ratios, liquidity ratios, leverage ratios, and growth rates.

```APIDOC
## GET /financial-metrics/snapshot

### Description
Retrieves a snapshot of key financial metrics for a company.

### Method
GET

### Endpoint
/financial-metrics/snapshot

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol of the company.
- **date** (string) - Optional - The specific date for which to retrieve the financial metrics (YYYY-MM-DD format).

### Response
#### Success Response (200)
- **profit_margin** (number) - Net income as a percentage of revenue.
- **return_on_equity** (number) - Net income as a percentage of shareholders' equity.
- **return_on_assets** (number) - Net income as a percentage of total assets.
- **return_on_invested_capital** (number) - Net operating profit after taxes as a percentage of invested capital.
- **asset_turnover** (number) - Revenue divided by average total assets.
- **inventory_turnover** (number) - Cost of goods sold divided by average inventory.
- **receivables_turnover** (number) - Revenue divided by average accounts receivable.
- **days_sales_outstanding** (number) - Average accounts receivable divided by revenue over the period.
- **operating_cycle** (number) - Inventory turnover + receivables turnover.
- **working_capital_turnover** (number) - Revenue divided by average working capital.
- **current_ratio** (number) - Current assets divided by current liabilities.
- **quick_ratio** (number) - Quick assets divided by current liabilities.
- **cash_ratio** (number) - Cash and cash equivalents divided by current liabilities.
- **operating_cash_flow_ratio** (number) - Operating cash flow divided by current liabilities.
- **debt_to_equity** (number) - Total debt divided by shareholders' equity.
- **debt_to_assets** (number) - Total debt divided by total assets.
- **interest_coverage** (number) - EBIT divided by interest expense.
- **revenue_growth** (number) - Year-over-year growth in revenue.
- **earnings_growth** (number) - Year-over-year growth in earnings.
- **book_value_growth** (number) - Year-over-year growth in book value.
- **earnings_per_share_growth** (number) - Growth in earnings per share over the period.
- **free_cash_flow_growth** (number) - Growth in free cash flow over the period.
- **operating_income_growth** (number) - Growth in operating income over the period.
- **ebitda_growth** (number) - Growth in EBITDA over the period.
- **payout_ratio** (number) - Dividends paid as a percentage of net income.
- **earnings_per_share** (number) - Net income divided by weighted average shares outstanding.
- **book_value_per_share** (number) - Shareholders' equity divided by shares outstanding.
- **free_cash_flow_per_share** (number) - Free cash flow divided by shares outstanding.

#### Response Example
{
  "profit_margin": 0.15,
  "return_on_equity": 0.20,
  "return_on_assets": 0.10,
  "return_on_invested_capital": 0.18,
  "asset_turnover": 1.2,
  "inventory_turnover": 5.0,
  "receivables_turnover": 10.0,
  "days_sales_outstanding": 36.5,
  "operating_cycle": 41.5,
  "working_capital_turnover": 3.0,
  "current_ratio": 2.5,
  "quick_ratio": 1.5,
  "cash_ratio": 0.8,
  "operating_cash_flow_ratio": 1.2,
  "debt_to_equity": 0.5,
  "debt_to_assets": 0.3,
  "interest_coverage": 5.0,
  "revenue_growth": 0.10,
  "earnings_growth": 0.12,
  "book_value_growth": 0.08,
  "earnings_per_share_growth": 0.15,
  "free_cash_flow_growth": 0.11,
  "operating_income_growth": 0.09,
  "ebitda_growth": 0.13,
  "payout_ratio": 0.30,
  "earnings_per_share": 2.50,
  "book_value_per_share": 25.00,
  "free_cash_flow_per_share": 1.50
}

#### Error Responses
- **400 Bad Request**: Returned if the request parameters are invalid.
- **401 Unauthorized**: Returned if the API key is invalid or missing.
- **402 Payment Required**: Returned if the user's subscription does not grant access to this endpoint.
```

--------------------------------

### Fetch Interest Rates Snapshot

Source: https://docs.financialdatasets.ai/api/macro/interest-rates/snapshot

Use this Python snippet to make a GET request to the Interest Rates Snapshot API. Ensure your API key is included in the request headers. The response is then parsed to extract the interest rates.

```python
import requests

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

# create the URL
url = 'https://api.financialdatasets.ai/macro/interest-rates/snapshot'

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

# parse snapshot from the response
interest_rates = response.json().get('interest_rates')
```

--------------------------------

### Get Latest Stock Price Snapshot

Source: https://docs.financialdatasets.ai/quickstart

Retrieve the real-time price snapshot for a given stock ticker.

```APIDOC
## GET /prices/snapshot

### Description
Fetches the latest real-time price snapshot for a given stock ticker.

### Method
GET

### Endpoint
/prices/snapshot

### Parameters
#### Query Parameters
- **ticker** (string) - Required - The stock ticker symbol (e.g., NVDA).

### Request Example
```python
import requests

headers = {"X-API-KEY": "your_api_key_here"}
url = "https://api.financialdatasets.ai/prices/snapshot?ticker=NVDA"
response = requests.get(url, headers=headers)
```

### Response
#### Success Response (200)
- **snapshot** (object) - An object containing the latest price information.
  - **close** (number) - The closing price of the stock.

### Response Example
```json
{
  "snapshot": {
    "close": 170.50
  }
}
```
```

--------------------------------

### Get Available Tickers

Source: https://docs.financialdatasets.ai/api/financials/balance-sheet-segments

Fetch a list of available tickers for which balance sheet segment data can be retrieved.

```APIDOC
## GET /financials/balance-sheets/segments/tickers

### Description
Retrieves a list of stock tickers for which balance sheet segment data is available.

### Method
GET

### Endpoint
https://api.financialdatasets.ai/financials/balance-sheets/segments/tickers/

### Parameters
None

### Response
#### Success Response (200)
- **tickers** (array) - A list of available stock ticker symbols.
```

--------------------------------

### Fetch Segmented Income Statements

Source: https://docs.financialdatasets.ai/api/financials/income-statement-segments

Construct the API URL with desired parameters and make a GET request. Ensure 'requests' library is imported and 'headers' are properly configured.

```python
import requests

# set your query params
ticker = 'AAPL'
period = 'annual'
limit = 100
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/financials/income-statements/segments'
    f'?ticker={ticker}'
    f'&period={period}'
    f'&limit={limit}'
    f'&report_period_lte={report_period_lte}'
    f'&report_period_gte={report_period_gte}'
)

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

# parse segmented_financials from the response
segmented_financials = response.json().get('segmented_financials')
```
Tokens:
Raw