# Financial Datasets

> Financial Datasets is an agent-friendly REST API providing institutional-grade stock market data for AI agents, quantitative research, and financial applications.

Financial Datasets covers 27,000+ active and delisted US tickers with 30+ years of historical data, sub-200ms response times, and 99.98% uptime. All endpoints use simple GET/POST requests with API key authentication.

## Base URL & Authentication

Base URL: https://api.financialdatasets.ai

OpenAPI Spec: https://www.financialdatasets.ai/openapi.json

Authentication: Include your API key in the `X-API-KEY` header with every request.

No API key yet? An AI agent can create one right now: POST /agent/signup returns a key in one call. Full self-serve flow: https://www.financialdatasets.ai/skill.md

Example:
```
curl -H "X-API-KEY: YOUR_API_KEY" "https://api.financialdatasets.ai/financials/income-statements?ticker=AAPL&period=annual&limit=4"
```

## Endpoints

### Stocks

| Endpoint | Path | Method | Price |
|---|---|---|---|
| Earnings | /earnings | GET | $0.01 / request |
| Stock Prices | /prices | GET | $0.02 / request |
| SEC Filings | /filings | GET | $0.02 / request |
| Interest Rates | /macro/interest-rates | GET | $0.02 / request |
| Financial Metrics | /financial-metrics | GET | $0.04 / request |
| Financial Metrics Snapshot | /financial-metrics/snapshot | GET | $0.04 / request |
| Income Statements | /financials/income-statements | GET | $0.04 / request |
| Balance Sheets | /financials/balance-sheets | GET | $0.04 / request |
| Cash Flow Statements | /financials/cash-flow-statements | GET | $0.04 / request |
| Income Statement Segments | /financials/income-statements/segments | GET | $0.04 / request |
| Balance Sheet Segments | /financials/balance-sheets/segments | GET | $0.04 / request |
| Cash Flow Statement Segments | /financials/cash-flow-statements/segments | GET | $0.04 / request |
| Income Statement (As-Reported) | /financials/income-statements/as-reported | GET | $0.08 / request |
| Balance Sheet (As-Reported) | /financials/balance-sheets/as-reported | GET | $0.08 / request |
| Cash Flow Statement (As-Reported) | /financials/cash-flow-statements/as-reported | GET | $0.08 / request |
| Insider Trades | /insider-trades | GET | $0.04 / request |
| Institutional Holdings | /institutional-holdings | GET | $0.04 / request |
| News | /news | GET | $0.04 / request |
| Press Releases | /earnings/press-releases | GET | $0.04 / request |
| All Financial Statements | /financials | GET | $0.10 / request |
| All Segmented Financials | /financials/segments | GET | $0.10 / request |
| All Financial Statements (As-Reported) | /financials/as-reported | GET | $0.20 / request |
| Search (Screener) | /financials/search/screener | POST | $0.01 per 10 filters |
| Search (Line Items) | /financials/search/line-items | POST | $0.01 per 10 filters |

## Response Keys

All responses are JSON. Each endpoint returns data under a named key:

| Endpoint | Response Key |
|---|---|
| Income Statements | `income_statements` |
| Balance Sheets | `balance_sheets` |
| Cash Flow Statements | `cash_flow_statements` |
| All Financial Statements | `financials` |
| All Segmented Financials | `segmented_financials` |
| Income/Balance/Cash Flow Segments | `segmented_financials` |
| Income Statement (As-Reported) | `as_reported_income_statements` |
| Balance Sheet (As-Reported) | `as_reported_balance_sheets` |
| Cash Flow Statement (As-Reported) | `as_reported_cash_flow_statements` |
| All Financial Statements (As-Reported) | `as_reported_financials` |
| Financial Metrics | `financial_metrics` |
| Stock Prices | `prices` |
| Earnings | `earnings` |
| Insider Trades | `insider_trades` |
| Institutional Holdings | `institutional_holdings` |
| News | `news` |
| SEC Filings | `filings` |
| Press Releases | `press_releases` |
| Interest Rates | `interest_rates` |

## Endpoint Parameters

### Financial Statements (Income, Balance Sheet, Cash Flow, All)
- `ticker` or `cik` (required) — stock ticker or SEC CIK
- `period` (string) — `annual`, `quarterly`, or `ttm` (default: `annual`)
- `limit` (integer) — max results to return (default: 4, max: 100)
- `report_period` (YYYY-MM-DD) — exact report period filter
- `report_period_gte`, `report_period_lte`, `report_period_gt`, `report_period_lt` — range filters

### Segmented Financials (Income, Balance Sheet, Cash Flow Segments, All)
- `ticker` or `cik` (required)
- `period` — `annual` or `quarterly` only (no ttm, default: `annual`)
- `limit` (default: 4, max: 100)
- `report_period` filters (same as financial statements)

### As-Reported Financials (Income, Balance Sheet, Cash Flow As-Reported, All)
- `ticker` or `cik` (required)
- `period`: `annual` or `quarterly` only (no ttm, default: `annual`)
- `limit` (default: 4, max: 100)
- `report_period` filters (same as financial statements)
- Returns the as-filed line-item hierarchy under `line_items`, a recursive tree with `label` (filing-face wording), `full_label` (canonical taxonomy label), `value`, and `children`. Available from 2010 onward.

### Financial Metrics (Historical)
- `ticker` or `cik` (required)
- `period` — `annual`, `quarterly`, or `ttm`
- `limit` (default: 4)
- `report_period` filters

### Financial Metrics (Snapshot)
- `ticker` or `cik` (required)

### Stock Prices
- `ticker` (required)
- `interval` (required) — `day`, `week`, `month`, or `year`
- `start_date` (required, YYYY-MM-DD)
- `end_date` (required, YYYY-MM-DD)

### Earnings
- `ticker` (required)

### Press Releases
- `ticker` (required)
- `limit` (default: 4)

### Company Facts
- `ticker` or `cik` (required)

### Insider Trades
- `ticker` (required)
- `limit` (default: 10, max: 5000)
- `filing_date`, `filing_date_gte`, `filing_date_lte`, `filing_date_gt`, `filing_date_lt` (YYYY-MM-DD)

### Institutional Ownership
- `ticker` or `investor` (required, mutually exclusive)
- `limit` (default: 10, max: 1000)
- `report_period` filters

### News
- `ticker` (required)
- `limit` (default: 5, max: 10)

### SEC Filings
- `ticker` or `cik` (required)
- `filing_type` (optional, comma-separated, e.g. `10-K,10-Q`)
- `limit` (default: 10)

### Filing Items
- `ticker` or `cik` (required)
- `filing_type` (required: `10-K`, `10-Q`, or `8-K`)
- `year` (required for 10-K/10-Q)
- `quarter` (required for 10-Q: 1, 2, or 3)
- `item` (optional, specific sections to extract)

### Search (Screener) — POST with JSON body
```json
{
  "filters": [
    {"field": "revenue", "operator": "gt", "value": 1000000000},
    {"field": "sector", "operator": "eq", "value": "Technology"}
  ],
  "limit": 10
}
```
Operators: `gt`, `lt`, `gte`, `lte`, `eq`, `in`

### Search (Line Items) — POST with JSON body
```json
{
  "tickers": ["AAPL", "MSFT"],
  "line_items": ["revenue", "net_income", "earnings_per_share"],
  "period": "ttm",
  "limit": 5
}
```

### Interest Rates
- `bank` (required, e.g. FED, ECB, BOJ)
- `start_date`, `end_date` (YYYY-MM-DD)

## Example

```python
import requests

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

# Get AAPL annual income statements
url = (
    "https://api.financialdatasets.ai/financials/income-statements"
    "?ticker=AAPL"
    "&period=annual"
    "&limit=4"
)

response = requests.get(url, headers=headers)
income_statements = response.json()["income_statements"]

# Each record contains: ticker, report_period, period, currency, revenue,
# cost_of_revenue, gross_profit, operating_income, net_income, eps, and more.
```

## Free Helper Endpoints

These endpoints require no authentication:

- `GET /financials/income-statements/tickers` — tickers with financial statement data
- `GET /financials/income-statements/segments/tickers` — tickers with segment data
- `GET /earnings/tickers` — tickers with earnings data
- `GET /filings/tickers` — tickers with SEC filings
- `GET /filings/types` — valid SEC filing types
- `GET /filings/items/types` — extractable sections per filing type
- `GET /prices/tickers` — tickers with price history
- `GET /prices/snapshot/tickers` — tickers with price snapshots
- `GET /macro/interest-rates/banks` — available central banks
- `GET /financials/search/screener/filters` — available screener filter fields and operators

## Subscription Plans

| Plan | Price | Key Features |
|---|---|---|
| Developer | $200/mo ($2,000/yr) | Individual license, 1,000 req/min, all endpoints |
| Pro | $2,000/mo ($20,000/yr) | Unlimited requests, data redistribution, webhooks |
| Enterprise | Custom | Dedicated infrastructure, SLAs, custom feeds |

## Per-Request Pricing Summary

| Price | Endpoints |
|---|---|
| $0.01 | Earnings, Search (per 10 filters) |
| $0.02 | Stock Prices, Interest Rates, SEC Filings |
| $0.04 | Financial Metrics, Insider Trades, News, Institutional Holdings, Income Statements, Balance Sheets, Cash Flow Statements, Segmented Financials, Press Releases |
| $0.10 | All Financial Statements (bundled), All Segmented Financials (bundled) |

## Key Statistics

- 30+ years of historical fundamentals
- 27,000+ global stocks
- < 200ms response times
- 99.99% uptime and availability

## AI Agent Resources

- **Agent self-signup skill**: https://www.financialdatasets.ai/skill.md - open your own funded account fully autonomously (POST /agent/signup, mint a Stripe checkout link, owner pays)
- **OpenAPI Spec**: https://www.financialdatasets.ai/openapi.json
- **MCP Server**: https://mcp.financialdatasets.ai/ — use with Claude, Cursor, and other MCP clients
- **API Docs**: https://docs.financialdatasets.ai/introduction

## Links

- Website: https://www.financialdatasets.ai
- Pricing: https://www.financialdatasets.ai/pricing
- Support: support@financialdatasets.ai
- Twitter: https://x.com/findatasets