Fundamentaly API docs

Reference for the Fundamentaly API: every endpoint with parameters, credits and examples in cURL and Python. Earnings calendar, results, estimates, guidance, insider trades, short interest, supply chains, prices and macro.

Authentication

Send your key as a bearer token: Authorization: Bearer fk_live_YOUR_KEY. Base URL: https://api.fundamentaly.io/v1. Only successful (2xx) responses cost credits. An endpoint that takes a list of companies costs its price for every company in the request.

Errors

Company

Who is covered.

CEO history

GET /v1/ceo-history/{ticker}, 1 credit per call

Full point-in-time CEO history for ticker — tenure spells (newest first) plus the sourced transition events.

  • ticker (string, required)
  • include_transitions (boolean)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/ceo-history/SBUX@US?include_transitions=False"

CEO on a date

GET /v1/ceo-history/{ticker}/at, 1 credit per call

Who was CEO of ticker on a given date (point-in-time lookup).

  • ticker (string, required)
  • date (string): As-of date YYYY-MM-DD (default: today)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/ceo-history/SBUX@US/at?date=2019-06-01"

All companies

GET /v1/companies, 1 credit per call

Every company in the universe with its ticker, name, exchange and sector. The starting point for the ticker_exchange values the other endpoints take.

curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/companies"

Logos

GET /v1/logos, 1 credit per call

Logo URLs for up to 100 companies in one call.

  • tickers (string, required): Comma-separated ticker_exchange values (e.g. AAPL@US,MSFT@US)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/logos?tickers=AAPL@US,MSFT@US"

Company data

GET /v1/reference-data, 1 credit per call

Get reference company data with optional filtering.

  • ticker (string): Filter by ticker (e.g., AAPL@US)
  • exchange (string): Filter by exchange (e.g., US, LN)
  • sector (string): Filter by GICS sector
  • sub_industry (string): Filter by GICS sub-industry
  • index (string): Filter by index (e.g., SP500, FTSE100)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/reference-data?index=SP500&sector=Information%20Technology"

Ecosystem

Who a company is compared with, sells to and buys from.

Customers

GET /v1/company/{ticker}/customers, 1 credit per call

Customers {ticker} names in its annual filings, plus companies that name {ticker} as a supplier.

  • ticker (string, required)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/company/NVDA@US/customers"

Suppliers

GET /v1/company/{ticker}/suppliers, 1 credit per call

Suppliers {ticker} names in its annual filings, plus companies that name {ticker} as a customer.

  • ticker (string, required)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/company/AAPL@US/suppliers"

Peers

GET /v1/company/{ticker}/peers, 1 credit per call

Peers of {ticker}, derived from same GICS sub-industry, ranked by market-cap proximity.

  • ticker (string, required)
  • limit (integer)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/company/AAPL@US/peers?limit=3"

Read-across

GET /v1/company/{ticker}/read-x-sentiment, 1 credit per call

Read-across sentiment for a company on a given date, today by default.

  • ticker (string, required)
  • as_of (string): ISO date (YYYY-MM-DD). Defaults to today. Must be <= today.
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/company/NVDA@US/read-x-sentiment"

Earnings & events

When companies report, and what the price does around it.

Earnings calendar

GET /v1/earnings-calendar, 1 credit per company

Get corporate events/earnings calendar with flexible filtering.

  • ticker (string): Filter by single ticker_exchange (e.g., AAPL@US). For multiple tickers use 'tickers' param instead.
  • tickers (string): Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US'). Takes precedence over 'ticker' if both provided.
  • start_date (string): Start date in YYYY-MM-DD format
  • end_date (string): End date in YYYY-MM-DD format
  • event_type (string): Filter by event type(s), comma-separated (e.g., earnings_conference_call,interim_statement)
  • index (string): Filter by index (e.g., FTSE100, SP500, STOXX600), or 'TOP' for the largest companies per day (see top_per_day)
  • top_per_day (integer): Only used with index=TOP: max earnings/sales events per calendar day, ranked by market cap
  • order_by_market_cap (boolean): When true, sort by market cap (largest first), then by date, then by ticker. When false (default), sort by date then by ticker. Ignored when filtering by a single ticker.
  • sort_order (string): Date sort direction: 'desc' (newest first, default) or 'asc' (oldest first). Acts as secondary sort when order_by_market_cap is true.
  • page (integer): Page number (1-indexed). Enables pagination when provided.
  • page_size (integer): Number of events per page (max 100). Only used when page is provided.
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/earnings-calendar?tickers=AAPL@US&start_date=2026-01-01&end_date=2026-12-31"

Earnings returns

GET /v1/earnings-results, 5 credits per company

Get realized event-period returns for corporate events in a date range.

  • start_date (string, required): Start date (YYYY-MM-DD)
  • end_date (string, required): End date (YYYY-MM-DD)
  • index (string): Filter by index (e.g., 'SP500')
  • tickers (string): Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')
  • type_group (string): Event type filter: 'earnings', 'sales', 'earnings-sales'
  • include_eps (boolean): Include EPS actual, estimate, and surprise for each event
  • return_type (string): Return type: total (raw), market_model (stock - benchmark), beta_adjusted (stock - beta*benchmark)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/earnings-results?start_date=2026-07-28&end_date=2026-07-31&tickers=MSFT@US&include_eps=True&return_type=beta_adjusted"

Price around earnings

GET /v1/earnings-performance, 5 credits per company

Get stock performance around corporate events.

  • ticker (string): Ticker in format TICKER@EXCHANGE (e.g., AAPL@US). For multiple tickers use 'tickers' instead.
  • tickers (string): Comma-separated tickers (e.g., 'AAPL@US,MSFT@US'). Returns results keyed by ticker. Takes precedence over ticker.
  • num_events (integer): Number of most recent earnings events to include
  • pre_days (integer): Number of trading days before event window to include (0 = none)
  • post_days (integer): Number of trading days after event window to include (0 = none)
  • event_period (string): Event period as 'start-end' range, e.g., '0-1' (days 0,1 — the default; canonical close(t-1)→close(t+1) reaction window), '-1-1' (days -1,0,1), '0-0' (day 0 only). Overrides event_window if provided.
  • event_window (integer): Symmetric days before/after event (legacy; baselines at close(-window-1)). When 0 and event_period unset, the canonical event_period='0-1' applies. Ignored if event_period is set.
  • type_group (string): Filter by type_group: 'earnings', 'sales', 'earnings-sales' (both), or 'other'. Recommended over event_type.
  • event_type (string): Deprecated: use type_group instead. Event type filter(s), comma-separated.
  • include_upcoming (boolean): Include upcoming events whose pre-period has already started (at least 1 trading day of pre_days window is in the past)
  • return_type (string): Return type: total (raw), market_model (stock - benchmark), beta_adjusted (stock - beta*benchmark)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/earnings-performance?ticker=NVDA@US&num_events=2&type_group=earnings&return_type=market_model"

Earnings drivers

GET /v1/earnings-theme, 1 credit per company

Get AI-generated earnings theme summaries — one sentence per ticker describing what consistently drives the stock around earnings.

  • tickers (string, required): Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/earnings-theme?tickers=NVDA@US,AAPL@US"

Earnings moves

GET /v1/earnings-volatility, 5 credits per company

Get earnings volatility summary for multiple tickers in a single request.

  • tickers (string): Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')
  • index (string): Index name (e.g., 'SP500'). Alternative to tickers.
  • num_events (integer): Number of historical events to analyze
  • type_group (string): Event type filter: 'earnings', 'sales', 'earnings-sales'
  • include_events (boolean): Include individual event breakdowns per ticker
  • return_type (string): Return type: total (raw), market_model (stock - benchmark), beta_adjusted (stock - beta*benchmark)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/earnings-volatility?tickers=NVDA@US,MSFT@US&num_events=8"

Implied move

GET /v1/implied-earnings-move, 5 credits per company

Get options-implied earnings move for upcoming earnings events.

  • ticker (string): One or more tickers, comma-separated (e.g., 'AAPL@US,MSFT@US')
  • event (string): Earnings event period (e.g., 'Q4 2025', 'Q1 2026'). Overrides days_ahead.
  • days_ahead (integer): Look-ahead window for upcoming earnings (days)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/implied-earnings-move?ticker=ORCL@US,CVX@US&days_ahead=30"

Estimates

What the Street expects, and whether it was right.

Revisions

GET /v1/estimate-revisions, 1 credit per company

How the consensus moved — the dated path of each estimate, not just today's level.

  • tickers (string): Comma-separated ticker_exchange values (e.g., 'AAPL@US')
  • index (string): Index name. Alternative to tickers.
  • metric (string): Comma-separated metrics: 'eps', 'revenue'. Default: eps.
  • period (string): Filter by period type: 'annual' or 'quarter'
  • fiscal_period_end_date (string): Restrict to one fiscal period end (YYYY-MM-DD)
  • since (string): Only snapshots on/after this date (YYYY-MM-DD). Default: 90 days back.
  • forward_only (boolean): Only periods that have not ended yet
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/estimate-revisions?tickers=AAPL@US&metric=eps,revenue"

Consensus

GET /v1/estimates, 1 credit per company

Forward analyst consensus for multiple tickers, with the metric as data.

  • tickers (string): Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')
  • index (string): Index name (e.g., 'SP500'). Alternative to tickers.
  • metric (string): Comma-separated metrics: 'eps', 'revenue'. Default: all.
  • period (string): Filter by period type: 'annual' or 'quarter'
  • fiscal_year (integer): Filter by fiscal year (e.g., 2026)
  • fiscal_period (string): Filter by fiscal period: Q1, Q2, Q3, Q4
  • limit (integer): Max periods per ticker (default: 20) — applied before metric expansion
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/estimates?tickers=AAPL@US&period=quarter&limit=2"

Surprises

GET /v1/surprises, 1 credit per company

Reported actual vs expected — EPS and revenue — with the metric as data.

  • tickers (string): Comma-separated ticker_exchange values (e.g., 'AAPL@US')
  • index (string): Index name. Alternative to tickers.
  • metric (string): Comma-separated metrics: 'eps', 'revenue'. Default: both.
  • period (string): Revenue only: 'annual' or 'quarter'
  • fiscal_year (integer): Filter by fiscal year (e.g., 2026)
  • num_events (integer): Recent prints per ticker per metric (default: 8)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/surprises?tickers=AAPL@US&num_events=2"

Deep estimates

GET /v1/deep-estimates, 5 credits per company

Deep estimates — issuer-compiled analyst consensus, the Street's expectations bar for upcoming periods, line by line.

  • tickers (string): Comma-separated ticker_exchange (e.g. 'KNEBV@HE,BAYN@GR')
  • index (string): Index name. Alternative to tickers.
  • canonical_metric (string): Filter to a canonical metric, e.g. 'revenue', 'eps_adjusted'
  • metric_search (string): Case-insensitive substring match on the verbatim metric label
  • period_type (string): Q1|Q2|Q3|Q4|H1|H2|9M|FY
  • fiscal_year (integer): Fiscal year the period ends in
  • estimates_only (boolean): Exclude reported-actual columns
  • exclude_submetrics (boolean): Drop derived sub-lines (growth rates, margins)
  • as_of (string): Point-in-time: the snapshot on/before this date (YYYY-MM-DD). Defaults to latest.
  • limit (integer): Max records per ticker
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/deep-estimates?tickers=KNEBV@HE&canonical_metric=revenue&limit=2"

Deep estimates coverage

GET /v1/deep-estimates/coverage, 1 credit per call

Which companies have deep-estimates coverage, how fresh it is, and how deep.

  • include_unmapped (boolean): Include source companies not in our universe (ticker_exchange NULL)
  • max_stale_days (integer): Only companies whose consensus is at most this many days old
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/deep-estimates/coverage?view=coverage&max_stale_days=90&include_unmapped=False"

Target prices

GET /v1/deep-estimates/summary, 1 credit per company

Deep-estimates target price and recommendation split per ticker.

  • tickers (string): Comma-separated ticker_exchange
  • index (string): Index name. Alternative to tickers.
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/deep-estimates/summary?view=summary&tickers=KNEBV@HE"

Reported financials

What companies actually reported.

Financials

GET /v1/fundamental-kpis/{ticker}, 5 credits per call

Everything a company reported: statements, ratios and the revenue split.

  • ticker (string, required)
  • include (string): Comma-separated sections: statements, ratios, segments
  • period (string): Q1, Q2, Q3, Q4 or FY
  • year (integer): Fiscal year, e.g. 2025
  • statement (string): income_statement | balance_sheet | cash_flow
  • metric_name (string): Filter statement lines by metric (partial match)
  • ratio_category (string): margin | leverage | liquidity
  • segment_metric (string): Which metric to decompose
  • segment_dimension (string): geography | business_segment | product_service | where
  • include_rollups (boolean): Include segment roll-up/alias members. Off by default: summing them double-counts.
  • tags (string): 'canonical' (default): the 25 curated metrics, synonyms resolved and subtotals derived. 'all': every us-gaap concept the filer tagged, in the order and wording of the filing.
  • scope (string): With tags=all: 'face' | 'other' | 'all'
  • limit (integer)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/fundamental-kpis/AAPL@US?include=statements&statement=income_statement&period=FY&year=2025&limit=3"

Financials coverage

GET /v1/fundamental-kpis/{ticker}/coverage, 1 credit per call

What we hold for this company, and over what span — before asking for it.

  • ticker (string, required)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/fundamental-kpis/AAPL@US/coverage"

Management guidance

GET /v1/guidance/{ticker}, 1 credit per call

All management guidance for ticker, every metric and every period.

  • ticker (string, required)
  • metric_key (string): Filter to a single metric_key
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/guidance/MAR@US"

Prices & risk

How the stock trades.

Daily prices

GET /v1/market-data/{ticker}, 1 credit per call

Get market data (daily prices and volume) for a specific ticker.

  • ticker (string, required)
  • start_date (string, required): Start date in YYYY-MM-DD format
  • end_date (string, required): End date in YYYY-MM-DD format
  • fields (string): Comma-separated subset of fields to return, e.g. 'date,close_price'. Available: date, close_price, close_price_adjusted, close_volume, currency, market_cap, market_cap_usd, pe_ttm, pe_ratio, forward_pe, ev_ebitda. date is always included. Omit for the default set (everything except forward_pe and ev_ebitda, which are opt-in).
  • resample (string): Frequency: D (daily, default), W (week-ending close), M (month-end close). Each bucket returns its last observation; the newest bucket is partial.
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/market-data/AAPL@US?start_date=2026-07-01&end_date=2026-09-05&fields=date,close_price,market_cap_usd&resample=W"

News

GET /v1/news, 1 credit per company

Recent deduped news per company.

  • tickers (string, required): Comma-separated ticker_exchange values (e.g. VZ@US,HWDN@LN)
  • days_back (integer): Look-back window in days
  • limit (integer): Max items per ticker (legacy, non-paginated mode only)
  • canonical_only (boolean): Collapse syndicated duplicates to one row per event
  • trusted_only (boolean): Only specialised/trade-press (site-scoped) items
  • page (integer): Page number (1-indexed). Enables pagination when provided, returning a flat newest-first feed merged across all tickers.
  • page_size (integer): Number of articles per page (max 100). Only used when page is provided.
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/news?tickers=VOD@LN&days_back=30&page=1&page_size=2"

Returns

GET /v1/price-returns, 5 credits per company

Get price returns for multiple tickers over a given period.

  • tickers (string, required): Comma-separated ticker_exchange values (e.g. AAPL@US,MSFT@US)
  • period (string): Return period: 1d, 1w, 1m, 3m, 6m, 1y, wtd, mtd, ytd
  • return_type (string): Return type: total (raw), market_model (stock - benchmark), beta_adjusted (stock - beta*benchmark)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/price-returns?tickers=AAPL@US,ASML@NA&period=ytd&return_type=beta_adjusted"

Return breakdown

GET /v1/risk-model/{ticker}, 5 credits per call

Latest market and sector sensitivity, plus the last N days of return decomposition for ticker.

  • ticker (string, required)
  • days (integer): Trading days of decomposition to return
  • summary_only (boolean): Return the sensitivities and cumulative contributions only, dropping the per-day array. Same window, ~1/20th the payload.
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/risk-model/AAPL@US?days=90&summary_only=True"

Market sensitivity

GET /v1/risk-model/{ticker}/exposures, 5 credits per call

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.

  • ticker (string, required)
  • days (integer): Trading days of history
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/risk-model/AAPL@US/exposures?days=365"

Seasonality

GET /v1/seasonality/{ticker}, 5 credits per call

Monthly seasonality profile for one ticker.

  • ticker (string, required)
  • years (integer): Lookback window in years
  • benchmark (string): Override benchmark ticker_exchange (defaults to the ticker's regional index ETF)
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/seasonality/VZ@US?years=15"

Sector returns

GET /v1/sector-returns, 1 credit per company

Calculate returns by GICS sector over a date range.

  • start_date (string, required): Start date in YYYY-MM-DD format
  • end_date (string, required): End date in YYYY-MM-DD format
  • exchange (string): Filter by exchange (e.g., US, LN, GR)
  • index (string): Filter by index name (e.g., S&P 500, FTSE 100)
  • include_all_tickers (boolean): Include all tickers with their returns in each sector (not just top/bottom 3)
  • include_market_cap (boolean): Include latest market cap (from end_date) for each ticker
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/sector-returns?start_date=2026-08-01&end_date=2026-09-09&index=FTSE100"

Positioning

Who is short, who is buying, and the read-across.

Insider trades

GET /v1/insider-transactions, 1 credit per company

Get insider transactions across multiple tickers with filtering options.

  • tickers (string): Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')
  • exchange (string): Exchange filter (e.g., 'US')
  • index (string): Index filter (e.g., 'SP500')
  • start_date (string): Start date (YYYY-MM-DD)
  • end_date (string): End date (YYYY-MM-DD)
  • transaction_types (string): Comma-separated transaction types (e.g., 'Buy,Sell')
  • transaction_groups (string): Comma-separated coarse groups (Buy,Sell,Award,Exercise,Tax,Other)
  • limit (integer): Maximum number of results
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/insider-transactions?tickers=NVDA@US,AAPL@US&transaction_groups=Buy,Sell&start_date=2026-01-01&limit=5"

Short interest

GET /v1/short-interest, 1 credit per company

Latest short interest reading per ticker, for US and UK equities.

  • ticker (string): One or more tickers, comma-separated (e.g., 'AAPL@US,GME@US')
  • index (string): Index name (e.g., 'SP500'). Alternative to ticker.
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/short-interest?ticker=GME@US,BARC@LN"

Shorts into earnings

GET /v1/short-interest/earnings-comparison, 1 credit per call

Compare the latest short interest reading with the reading at the equivalent point (same number of days) before the previous earnings date.

  • ticker (string, required): One ticker (US only, e.g. 'AAPL@US')
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/short-interest/earnings-comparison?ticker=AAPL@US"

Short interest history

GET /v1/short-interest/history, 1 credit per call

Short interest as a time series for one ticker, oldest first.

  • ticker (string, required): One ticker (e.g. 'GME@US' or 'BARC@LN')
  • start_date (string): Earliest date to return (YYYY-MM-DD)
  • end_date (string): Latest date to return (YYYY-MM-DD)
  • limit (integer): Keep only the N most recent points
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/short-interest/history?ticker=WMT@US&limit=10"

Macro

What is happening outside the company.

Macro calendar

GET /v1/macro-events, 1 credit per call

Flexible macro-economic events endpoint.

  • start_date (string): Start date YYYY-MM-DD (default: today)
  • end_date (string): End date YYYY-MM-DD (default: today + 14 days)
  • currency (string): Comma-separated currency codes (e.g., USD,EUR,GBP)
  • country (string): Country code mapped to currency (e.g., US, GB, EU, JP)
  • category (string): Event category (Inflation, Central Bank, Employment, GDP, Manufacturing, Services, Housing, Other)
  • event_name (string): Exact event name filter (e.g., CPI m/m)
  • include_surprises (boolean): Include surprise stats (beat/miss rate) per event
  • include_history (boolean): Include last N historical releases per event
  • history_count (integer): Number of past releases when include_history=true
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/macro-events?start_date=2026-09-01&end_date=2026-09-30&currency=USD&include_surprises=True"

Macro movers

GET /v1/macro-sensitivity, 5 credits per call

Get stocks most sensitive to surprises in a specific macro event.

  • event_name (string, required): Macro event name (e.g., 'CPI m/m')
  • currency (string, required): Macro event currency (e.g., 'USD')
  • surprise_direction (string): 'above_estimate' (actual > forecast), 'below_estimate' (actual < forecast), or 'both'. Legacy values 'positive'/'negative' still accepted.
  • filtering_mode (string): Ranking mode. Vanilla: 'top', 'bottom', 'absolute'. Ex-market (excess over benchmark): 'top_ex_market', 'bottom_ex_market', 'absolute_ex_market'
  • index (string): Filter by index (SP500, FTSE100, STOXX600, NIFTY50)
  • min_events (integer): Minimum events for inclusion
  • min_coverage (number): Minimum coverage percentage (0-100). Filters out stocks that weren't present for enough events (e.g. new IPOs). Applied to the relevant direction.
  • limit (integer): Max results
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/macro-sensitivity?event_name=CPI%20m%2Fm&currency=USD&index=SP500&limit=3"

Macro releases

GET /v1/macro-sensitivity/events, 1 credit per call

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.

curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/macro-sensitivity/events"

Macro series

GET /v1/macro-indices/series, 1 credit per call

Find macro series. Use this first to discover the code you need, then call /observations with it.

  • geo (string): Comma-separated ISO-2 countries, e.g. DE,FR,GB
  • family (string): Comma-separated families: price, volume_production, volume_retail, turnover_retail, volume_tourism, volume_travel, employment, lodging_kpi, confidence, weight
  • code (string): Comma-separated COICOP/NACE codes, e.g. CP0122,C1107
  • search (string): Case-insensitive substring match on the series label
  • measure (string): GB price measure: CPI (default), CPIH, or 'all' for both
  • classification (string): Comma-separated code systems: ECOICOP2, NACE2, EU_BCS, ONS_COICOP, ONS_RSI, BLS_CPI, BLS_PPI, BLS_CES, BEA_PCE, TSA, UMICH, STR_US
  • limit (integer): Max series to return
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/macro-indices/series?search=retail&limit=3"

Macro data

GET /v1/macro-indices/observations, 1 credit per call

Observations for the matching series. Levels, not rates — compute YoY yourself, with one documented exception (below).

  • code (string): Comma-separated COICOP/NACE codes, e.g. CP0122,C1107
  • geo (string): Comma-separated ISO-2 countries, e.g. DE,FR,GB
  • family (string): Comma-separated families: price, volume_production, volume_retail, turnover_retail, volume_tourism, volume_travel, employment, lodging_kpi, confidence, weight
  • series_key (string): Exact series_key, overrides the other filters
  • start_period (string): Earliest period, inclusive. YYYY-MM (monthly), YYYY (annual) or YYYY-MM-DD (daily/weekly)
  • end_period (string): Latest period, inclusive. Same shapes as start_period
  • measure (string): GB price measure: CPI (default), CPIH, or 'all' for both
  • classification (string): Comma-separated code systems: ECOICOP2, NACE2, EU_BCS, ONS_COICOP, ONS_RSI, BLS_CPI, BLS_PPI, BLS_CES, BEA_PCE, TSA, UMICH, STR_US
  • limit (integer): Max observations to return
curl -H "Authorization: Bearer fk_live_YOUR_KEY" "https://api.fundamentaly.io/v1/macro-indices/observations?geo=GB&family=price&start_period=2026-01&limit=3"

API overview | Get your API key | OpenAPI spec