# Fundamentaly API

> A REST API for earnings calendars, results, consensus estimates, management guidance, insider trades, short interest, supply chains and prices across 1,300+ companies in the US, Europe, the UK and India. 1,000 free credits on your first key.

Fundamentaly is an earnings data platform for investors (https://app.fundamentaly.io). Everything in the app is also available as a REST API.

## Getting started

- [API overview](https://app.fundamentaly.io/api): what it covers and what it costs
- [API docs](https://app.fundamentaly.io/api-docs): every endpoint with parameters and examples
- [OpenAPI spec](https://app.fundamentaly.io/openapi.json)
- Keys: sign in and create one on https://app.fundamentaly.io/account. 1,000 free credits on the first key, valid 30 days, no card needed.
- Auth: `Authorization: Bearer fk_live_YOUR_KEY`. Base URL: `https://api.fundamentaly.io/v1`.
- Pricing: one credit per company per call; errors cost nothing; top up any amount.

## Coverage

1,337 companies: US 601, Europe 530, UK 152, India 54.

## Endpoints

### Company

- [CEO history](https://app.fundamentaly.io/api-docs#ep-ceo-history-ticker): `GET /v1/ceo-history/{ticker}`. Full point-in-time CEO history for ticker — tenure spells (newest first) plus the sourced transition events.
- [CEO on a date](https://app.fundamentaly.io/api-docs#ep-ceo-history-ticker-at): `GET /v1/ceo-history/{ticker}/at`. Who was CEO of ticker on a given date (point-in-time lookup).
- [All companies](https://app.fundamentaly.io/api-docs#ep-companies): `GET /v1/companies`. Every company in the universe with its ticker, name, exchange and sector. The starting point for the ticker_exchange values the other endpoints take.
- [Logos](https://app.fundamentaly.io/api-docs#ep-logos): `GET /v1/logos`. Logo URLs for up to 100 companies in one call.
- [Company data](https://app.fundamentaly.io/api-docs#ep-reference-data): `GET /v1/reference-data`. Get reference company data with optional filtering.

### Ecosystem

- [Customers](https://app.fundamentaly.io/api-docs#ep-company-ticker-customers): `GET /v1/company/{ticker}/customers`. Customers {ticker} names in its annual filings, plus companies that name {ticker} as a supplier.
- [Suppliers](https://app.fundamentaly.io/api-docs#ep-company-ticker-suppliers): `GET /v1/company/{ticker}/suppliers`. Suppliers {ticker} names in its annual filings, plus companies that name {ticker} as a customer.
- [Peers](https://app.fundamentaly.io/api-docs#ep-company-ticker-peers): `GET /v1/company/{ticker}/peers`. Peers of {ticker}, derived from same GICS sub-industry, ranked by market-cap proximity.
- [Read-across](https://app.fundamentaly.io/api-docs#ep-company-ticker-read-x-sentiment): `GET /v1/company/{ticker}/read-x-sentiment`. Read-across sentiment for a company on a given date, today by default.

### Earnings & events

- [Earnings calendar](https://app.fundamentaly.io/api-docs#ep-earnings-calendar): `GET /v1/earnings-calendar`. Get corporate events/earnings calendar with flexible filtering.
- [Earnings returns](https://app.fundamentaly.io/api-docs#ep-earnings-results): `GET /v1/earnings-results`. Get realized event-period returns for corporate events in a date range.
- [Price around earnings](https://app.fundamentaly.io/api-docs#ep-earnings-performance): `GET /v1/earnings-performance`. Get stock performance around corporate events.
- [Earnings drivers](https://app.fundamentaly.io/api-docs#ep-earnings-theme): `GET /v1/earnings-theme`. Get AI-generated earnings theme summaries — one sentence per ticker describing what consistently drives the stock around earnings.
- [Earnings moves](https://app.fundamentaly.io/api-docs#ep-earnings-volatility): `GET /v1/earnings-volatility`. Get earnings volatility summary for multiple tickers in a single request.
- [Implied move](https://app.fundamentaly.io/api-docs#ep-implied-earnings-move): `GET /v1/implied-earnings-move`. Get options-implied earnings move for upcoming earnings events.

### Estimates

- [Revisions](https://app.fundamentaly.io/api-docs#ep-estimate-revisions): `GET /v1/estimate-revisions`. How the consensus moved — the dated path of each estimate, not just today's level.
- [Consensus](https://app.fundamentaly.io/api-docs#ep-estimates): `GET /v1/estimates`. Forward analyst consensus for multiple tickers, with the metric as data.
- [Surprises](https://app.fundamentaly.io/api-docs#ep-surprises): `GET /v1/surprises`. Reported actual vs expected — EPS and revenue — with the metric as data.
- [Deep estimates](https://app.fundamentaly.io/api-docs#ep-deep-estimates): `GET /v1/deep-estimates`. Deep estimates — issuer-compiled analyst consensus, the Street's expectations bar for upcoming periods, line by line.
- [Deep estimates coverage](https://app.fundamentaly.io/api-docs#ep-deep-estimates-coverage): `GET /v1/deep-estimates/coverage`. Which companies have deep-estimates coverage, how fresh it is, and how deep.
- [Target prices](https://app.fundamentaly.io/api-docs#ep-deep-estimates-summary): `GET /v1/deep-estimates/summary`. Deep-estimates target price and recommendation split per ticker.

### Reported financials

- [Financials](https://app.fundamentaly.io/api-docs#ep-fundamental-kpis-ticker): `GET /v1/fundamental-kpis/{ticker}`. Everything a company reported: statements, ratios and the revenue split.
- [Financials coverage](https://app.fundamentaly.io/api-docs#ep-fundamental-kpis-ticker-coverage): `GET /v1/fundamental-kpis/{ticker}/coverage`. What we hold for this company, and over what span — before asking for it.
- [Management guidance](https://app.fundamentaly.io/api-docs#ep-guidance-ticker): `GET /v1/guidance/{ticker}`. All management guidance for ticker, every metric and every period.

### Prices & risk

- [Daily prices](https://app.fundamentaly.io/api-docs#ep-market-data-ticker): `GET /v1/market-data/{ticker}`. Get market data (daily prices and volume) for a specific ticker.
- [News](https://app.fundamentaly.io/api-docs#ep-news): `GET /v1/news`. Recent deduped news per company.
- [Returns](https://app.fundamentaly.io/api-docs#ep-price-returns): `GET /v1/price-returns`. Get price returns for multiple tickers over a given period.
- [Return breakdown](https://app.fundamentaly.io/api-docs#ep-risk-model-ticker): `GET /v1/risk-model/{ticker}`. Latest market and sector sensitivity, plus the last N days of return decomposition for ticker.
- [Market sensitivity](https://app.fundamentaly.io/api-docs#ep-risk-model-ticker-exposures): `GET /v1/risk-model/{ticker}/exposures`. How sensitive the stock is to the market and its sector over time: beta drift, R² and idiosyncratic volatility, one row per day for charting.
- [Seasonality](https://app.fundamentaly.io/api-docs#ep-seasonality-ticker): `GET /v1/seasonality/{ticker}`. Monthly seasonality profile for one ticker.
- [Sector returns](https://app.fundamentaly.io/api-docs#ep-sector-returns): `GET /v1/sector-returns`. Calculate returns by GICS sector over a date range.

### Positioning

- [Insider trades](https://app.fundamentaly.io/api-docs#ep-insider-transactions): `GET /v1/insider-transactions`. Get insider transactions across multiple tickers with filtering options.
- [Short interest](https://app.fundamentaly.io/api-docs#ep-short-interest): `GET /v1/short-interest`. Latest short interest reading per ticker, for US and UK equities.
- [Shorts into earnings](https://app.fundamentaly.io/api-docs#ep-short-interest-earnings-comparison): `GET /v1/short-interest/earnings-comparison`. Compare the latest short interest reading with the reading at the equivalent point (same number of days) before the previous earnings date.
- [Short interest history](https://app.fundamentaly.io/api-docs#ep-short-interest-history): `GET /v1/short-interest/history`. Short interest as a time series for one ticker, oldest first.

### Macro

- [Macro calendar](https://app.fundamentaly.io/api-docs#ep-macro-events): `GET /v1/macro-events`. Flexible macro-economic events endpoint.
- [Macro movers](https://app.fundamentaly.io/api-docs#ep-macro-sensitivity): `GET /v1/macro-sensitivity`. Get stocks most sensitive to surprises in a specific macro event.
- [Macro releases](https://app.fundamentaly.io/api-docs#ep-macro-sensitivity-events): `GET /v1/macro-sensitivity/events`. The macro releases the sensitivity screen covers, with each one's currency, category and event count. Pick an event_name and currency here, then call macro-sensitivity with them.
- [Macro series](https://app.fundamentaly.io/api-docs#ep-macro-indices-series): `GET /v1/macro-indices/series`. Find macro series. Use this first to discover the code you need, then call /observations with it.
- [Macro data](https://app.fundamentaly.io/api-docs#ep-macro-indices-observations): `GET /v1/macro-indices/observations`. Observations for the matching series. Levels, not rates — compute YoY yourself, with one documented exception (below).