# 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,530 active and delisted US tickers with 30+ years of historical data, plus annual fundamentals for 674 UK companies listed on the London Stock Exchange, with 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

No key and no account: pay with x402. Send a request with no X-API-KEY header to a supported endpoint and the 402 response carries the payment terms in the PAYMENT-REQUIRED header (amount in USDC on Base, network eip155:8453). Sign the payment with your own wallet and retry with the PAYMENT-SIGNATURE header; the x402 client libraries do this for you. x402 endpoints: every documented GET data endpoint (36): prices, financial statements and segments, financial metrics, earnings, company facts, filings, news, insider trades and ownership, beneficial, activist and institutional holdings, index funds, macro series (interest rates, yield curve, inflation, labor, GPU prices), IPOs and KPIs. Not covered: /filings/items, /prices/snapshot/market, POST endpoints, and the free helper lists such as /prices/tickers. x402 requests cover the last 365 days of data. Guide: https://docs.financialdatasets.ai/x402

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; for a UK company add `market=UK` to the ticker (UK tickers keep the exchange's spelling, e.g. `RR.`), or pass `isin` alone
- `market` (string) — `US` (default) or `UK`; UK fundamentals are annual only, in the company's reporting currency (`currency` field). Guide: https://docs.financialdatasets.ai/guides/get-uk-fundamentals-python. Announcement: https://www.financialdatasets.ai/news/uk-fundamentals
- `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,530 US stocks, active and delisted
- 674 UK companies listed on the London Stock Exchange (annual fundamentals)
- < 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