Financial data, one API.

A read-only HTTP, WebSocket, and MCP interface over a 2.77 TB financial dataset — symbols, OHLC bars, fundamentals, short interest, SEC filings, news with sentiment, ownership, regulatory, macro, BTC options, plus a 34.8 M-row KOL tweet archive with 11.5 M mirrored images. Refreshed continuously, streamed live.

400
data sources
34.8 M
KOL tweets
11.5 M
tweet images
20.7 M
news articles
7,851
symbols
61.9 M
prediction markets
678 M
PM trades
2.77 TB
total dataset

01Quick start

Every endpoint is a plain GET that returns JSON. A Lumid PAT is required — pass it as Authorization: Bearer <pat>. Anonymous requests get 401. Every response carries your current budget in the x-ratelimit-limit / -remaining / -reset headers — read those rather than assuming a number, the tier differs per deployment.

Latest snapshot for one symbol

Profile, sector, market cap from the warehouse.
curl https://lum.id/findata/symbols/AAPL

OHLC bars — one liner

Defaults to last 365 d for 1d, 7 d for 5min, 1 d for 1min.
curl "https://lum.id/findata/ohlc/AAPL?interval=1d"

Real-time tick snapshot

Last-known tick across the Tier-C cache.
curl "https://lum.id/findata/quotes?symbols=AAPL,BTCUSD"

Stream live ticks (WebSocket)

Lumid bearer required. Subscribe by symbol after connect.
websocat -H="Authorization: Bearer $TOKEN" \
  wss://lum.id/findata/ws/quotes

Server-side screener

Sector / industry / market-cap / exchange / instrument-type.
curl "https://lum.id/findata/screener?sector=Technology&market_cap_min=1e12"

KOL tweets — archive search

34.8 M tweets, 2009-2026. Full-text + cashtag indexed.
curl "https://lum.id/findata/kols/tweets/search?q=earnings+beat"

News firehose by category

20.7 M articles (1995–present) across multiple wire and web feeds — millions carry full extracted body text plus per-article sentiment.
curl "https://lum.id/findata/news/latest?category=general&limit=20"

Tweet image (locally mirrored)

11.5 M cached images. by-url falls through to pbs.twimg.com if not cached.
curl -L "https://lum.id/findata/kols/media/by-url?u=<twitter-cdn-url>"

02Surface

Endpoints are grouped by data domain. Open any group in the OpenAPI spec or the guide for schemas and example payloads.

/Symbols
Universe lookup, search, profile, the canonical 7,851-symbol roster.
GET /symbols • /universe • /screener
/OHLC
1-min through 4-hour and dividend-adjusted daily bars across asset classes. US equity bars sourced from two independent feeds — merged automatically, with seamless failover if one has a gap.
GET /ohlc/{symbol}?interval=…
/Realtime
WS + SSE tick streams, last-tick snapshot, day range + 50/200-day SMAs, news WS, lag percentiles per source.
WSS /ws/quotes • /ws/news • SSE /quotes/stream • /quote-stats/{sym}
/Prediction Markets
Kalshi + Polymarket + Polymarket US: 61.9M markets (Polymarket back to 2021-01), 678M trades, ~250M L2 orderbook snapshots. Intraday OHLC at 1m/5m/15m/1h/1d — Polymarket candles union executed trade prints with orderbook-midprice (~7-month history); Kalshi candles back to 2021-06. Open-interest history, top holders, wallet leaderboard + PnL/positions/activity, cross-venue matched pairs. Polymarket US: the US-regulated exchange universe (10.6k markets) — filterable list + detail by slug. Live: CLOB-WSS recorder captures ~240 active Polymarket markets; consume via SSE /prediction-markets/stream.
GET /prediction-markets/candles/{venue}/{id}?interval=1|5|15|60|1440 • /trades/{venue}/{id} • /markets/search • /markets/polymarket_us[/{slug}] • SSE /stream
/Options
BTC options (Deribit-style): price observations + 15-min OHLC bars. Each row is one option contract — expiry, strike, otype (C/P), and price = option premium. Bars compute open/high/low/close from the observations; volume_traded is the vendor's (the observations carry no trade size). Empty buckets are omitted, not filled. 8.76M observations (2025-08 → 2026-07). Filter by otype / strike / expiry / time window.
GET /options/btc/events • /options/btc/ohlcv • /options/btc/contracts
/Fundamentals
Income, balance, and cash-flow statements from multiple sources — multi-source coverage for cross-validation. Wide-format latest or historical.
GET /fundamentals/{symbol}/latest • /fundamentals/{symbol}/history
/Analysis
Ratios, key metrics, point-in-time metrics snapshot (52-week stats, returns, beta), per-statement growth, financial scores, owner earnings, DCF. Technical indicators (SMA/EMA/RSI/MACD) from two independent sources for cross-validation.
GET /ratios/{sym} • /key-metrics/{sym} • /technical/{sym} • /dcf/{sym}
/Estimates
Analyst price targets, grades (current + history), upgrade-downgrade news.
GET /estimates/{symbol}/price-target • /estimates/{symbol}/grades
/Investors
13F top holders, insider transactions, fund ownership, gov / acquisitions.
GET /holders/{symbol}/top • /insider/{symbol}/transactions • /gov-trades/{sym}
/Events
Earnings calendar, transcripts, IPOs, mergers, FDA calendar.
GET /earnings/{symbol}/history • /transcripts/{sym} • /ipos
/News
20.7 M articles deduped across multiple wire and CSV feeds, including structured per-ticker sentiment (positive/negative/neutral + reasoning). Per-symbol, global firehose, or PG full-text search.
GET /news/latest • /news/search • /news/{symbol}
/KOL
Curated 3,846-handle roster + live cashtag SSE. 34.8 M-row Postgres archive (2009-2026, full-text + cashtag-indexed) with 11.5 M mirrored images served at /kols/media/.
GET /kols/tweets/search • /kols/{handle}/tweets/history • /kols/media/by-url
/ETF
Info, holdings, sector weights, asset-class exposure for 500 ETFs.
GET /etf/{sym}/info • /etf/{sym}/holdings
/Short Data & Filings
Bi-weekly FINRA short interest, daily off-exchange short volume. Machine-readable SEC risk-factor disclosures (primary/secondary/tertiary taxonomy). Plain-text 10-K annual-filing sections.
GET /short-interest/{sym} • /short-volume/{sym} • /risk-factors/{sym} • /10k-sections/{sym}
/Macro & Regulatory
Treasury rates, economic indicators, ESG, patents, lobbying, USA-spending, SEC filings, XBRL.
GET /macro/* • /filings/{sym} • /esg/{sym}/* • /xbrl/{sym}/*

03Realtime

Streams over the same hub: tick prices, news articles, KOL tweets. Both WSS /ws/quotes (bidirectional, subscribe-by-symbol) and GET /quotes/stream (SSE) are supported; WSS /ws/news is a news-only variant. Authentication via Lumid PAT (or X-API-Key).

StreamTransportSource tier
tick:<sym> /ws/quotes • /quotes/stream A — WS feed for US equities + crypto / forex. Multiple sources: crypto & forex run a primary + hot-standby WSS pair; US equities additionally have a secondary quote feed that auto-covers within seconds if the primary goes quiet. No manual intervention needed on any gap.
news:<sym> /ws/news B — news firehose poller (60 s)
pm:events /prediction-markets/stream (SSE) A — 1st-hand Polymarket CLOB WSS (~240 active markets)
last:tick:<sym> /quotes?symbols=… C — Tier-C Redis snapshot, evictable on memory pressure

Tier and lag are exposed live at GET /freshness (green/amber/red/gray per-endpoint SLA counts).

04Authentication

Routes are PAT-authenticated — an invalid token returns 401 (anonymous requests ride an anon-read tier). Auth goes through Lumid identity introspection; bring a Lumid PAT (lm_pat_live_… / rm_pat_live_…) or an RS256 JWT. Your per-minute budget comes back on every response in x-ratelimit-limit / -remaining / -reset.

# Bring your Lumid PAT (lm_pat_live_… / rm_pat_live_…) or JWT.
curl -H "Authorization: Bearer $LUMID_TOKEN" \
     https://lum.id/findata/symbols/AAPL

# Or via X-API-Key header — same effect.
curl -H "X-API-Key: $LUMID_TOKEN" \
     "https://lum.id/findata/quotes?symbols=AAPL"

05MCP — for agents

Most warehouse queries are also a Model Context Protocol tool, so an agent can pull fundamentals, holdings, filings, or the KOL archive without learning a separate HTTP shape. 90 tools, generated from the same endpoint definitions the HTTP API is built from — so the tool list is never out of date. Call tools/list for the authoritative set.

# Streamable-HTTP transport (MCP 2025-03-26, recommended):
curl -X POST https://lum.id/findata/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool names are <group>_<endpoint>. The groups, with one example each: fundamentals_latest, estimates_price_target, valuation_dcf, analysis_key_metrics, technical_indicators, earnings_calendar, transcripts_one, events_ipos, corpactions_dividends, news_search, kols_tweets_search, prediction-markets_trades_kalshi, investors_insider_transactions, institutional_holder_analytics, gov_trades_for_symbol, etf_info, reference_executives, macro_treasury_rates, regulatory_filings, marketextras_market_movers.

Not on MCP: symbols/universe/screener, OHLC bars, realtime quotes and streams, the catalog, and the ingress write surface are HTTP-only. They are high-cardinality or streaming shapes that don't fit a tool call — use the REST routes above for those.

06Ingress — write surface

The read API is paired with an ingress surface. Partners and agents push data with a Lumid PAT (per-role allowlist); the server stamps provenance and exposes the lineage chain back at /catalog/lineage/*. Discover what you may write with GET /catalog/ingress/writable, and the exact column shape of a target with GET /catalog/tables/{schema}/{table}/schema.json.

ModeEndpointWhen
Typed POST /ingest/{schema}/{table} JSON body with records in target-column shape. Idempotent.
Stream POST /ingest/{schema}/{table}/stream NDJSON, chunked transfer; one run row spans the whole stream. Gzip/zstd accepted.
File POST /ingest/{schema}/{table}/file Multipart upload — JSON / NDJSON / CSV / TSV / XML / YAML / Parquet / Arrow.
Blob POST /ingest/blob Images / PDFs / opaque binary. sha256 dedup; bytes land in sibling object storage, metadata in raw.blobs.
Webhook POST /webhook/{webhook_id} HMAC-SHA256 signed, no PAT. Provisioned by the operator (ask for one); rate-limited per webhook.

Writing to a table you don't yet have on the allowlist starts with an ingress proposal — the schema change is reviewed, not applied ad hoc (/catalog/ingress/proposals). The ingress routes are deliberately absent from the OpenAPI spec: they are operator-gated, not self-serve. Ask before you build against them.

07Refresh cadence

SourceCadence
Realtime tick stream Continuous — WS feed across asset classes (stocks, crypto, forex, indices) + secondary quote feed with live 1-min OHLC aggregation as a backup layer
Prediction-markets trades + orderbook Continuous WSS recorder; live trade prints + L2 deltas land in <1 s
Kalshi trades (incremental) Every 30 min
Non-stock 1-min OHLC Every 30 minutes (etf / crypto / forex / index / commodity)
Stock 1-min OHLC Daily at 04:30 UTC (primary feed lags ~3 days) + real-time secondary feed writes live bars continuously
Stock daily-adjusted EOD Daily at 05:15 UTC (dividend + non-split adjusted)
Analyst estimates Every 4 hours — grades, price-target, recommendation, ratings
Fundamentals statements Daily at 06:00 UTC — income / balance / cashflow + ratios + key-metrics + scores + earnings + growth + enterprise-values
Ownership (13F + insider + gov-trades) Daily at 07:00 UTC
Events + macro Daily at 07:30 UTC — earnings calendar, IPOs, treasury rates, economic indicators, COT, FDA
Market metadata Daily at 08:00 UTC — dividends, splits, market_cap
Social + news sentiment Daily at 09:00 UTC
Reference (profile, executives, ETF metadata) Weekly Sun 03:00 UTC + ETF holdings refresh
Regulatory (ESG, SEC filings, patents, lobbying) Weekly Sun 04:30 UTC
News articles (6 sources) Every 15 min — company-news, general, stock, crypto, forex, press releases + sentiment-enhanced feed every 4 h (structured per-ticker sentiment)
Short interest + short volume Weekly Sun 03:00 UTC — FINRA bi-weekly short interest + daily off-exchange short volume
Risk factors + 10-K sections Weekly Sun 05:00 UTC — machine-readable SEC risk-factor taxonomy + plain-text 10-K sections
Fundamentals (secondary source) Weekly Sun 07:00 UTC — income / balance / cash-flow (second provider, for cross-validation)
KOL tweets 3h / 12h / 24h tiers by tweet frequency (3,846-handle roster)
News firehose → SSE Polled every 60 s — event-driven WS fan-out

08Conventions

Times UTC ISO-8601. Dates are YYYY-MM-DD.
Symbols Upper-cased server-side. Crypto / forex use the upstream shape (e.g. BTCUSD, EURUSD).
Lineage The fields source, source_endpoint, source_run_id, ingest_ts, raw are intentionally stripped from responses. The API picks the canonical provider per surface.
Errors JSON {"detail": "…"} on 4xx / 5xx. 429 carries a Retry-After header.
Pagination Endpoints that return lists accept limit (max 1000) and offset; /ohlc uses a server-side row cap instead.
Failure mode Lumid unreachable while validating a presented token → 503 fail-closed.

09Query it from your own tools

Every endpoint is an authenticated GET returning JSON, so anything that can set an Authorization header can query the warehouse directly — no SDK, no export step. There is also a read-only Postgres wire endpoint (below) for tools that would rather speak SQL than HTTP. Two response shapes, so check once per endpoint: most list routes (/news/*, /kols/*, /prediction-markets/trades/*) return a bare JSON array of rows; a few wrap the rows in an envelope alongside a count (/ohlc → bars, /screener → hits). Unwrap that key and you have a table.

Postgres wire — psql, DBeaver, Metabase

A read-only Postgres endpoint straight onto the warehouse. Joins and filtering happen server-side, so this is the one to reach for when the REST shape fights you.
curl -O https://lum.id/findata/sql-ca.pem

psql "host=sql.lum.id port=5432 dbname=findata user=lumid_reader \
      sslmode=verify-full sslrootcert=sql-ca.pem"

Use verify-full, not require — require encrypts but accepts any certificate, so it does not stop an active man-in-the-middle. The CA above is the one that signs this endpoint, published over lum.id’s own TLS, and that is what anchors the trust. Credentials are issued per requester — ask for the password.

22 schemas, ~9990 tables. The session is read-only, capped at a two-minute statement_timeout and 40 shared connections, and refuses plaintext outright. market carries the OHLC hypertables (ohlc_1min, ohlc_5min, ohlc_daily); prediction_markets carries 34 tables of Polymarket and Kalshi markets, trades, per-interval candles, orderbook snapshots and wallet analytics; then fundamentals, news, macro, estimates, ownership, reference, instrument, events, regulatory, md.

SELECT symbol, date, close, volume
FROM market.ohlc_daily
WHERE symbol = 'AAPL'
ORDER BY date DESC LIMIT 5;

-- DuckDB can attach it directly, too.
INSTALL postgres; LOAD postgres;
ATTACH 'host=sql.lum.id port=5432 dbname=findata user=lumid_reader
        password=... sslmode=verify-full sslrootcert=sql-ca.pem'
  AS fd (TYPE postgres, READ_ONLY);

DuckDB — SQL straight over the API

Nothing to download. httpfs fetches, DuckDB does the SQL.
INSTALL httpfs; LOAD httpfs;

-- Attach your PAT once per session.
CREATE SECRET findata (
  TYPE http,
  EXTRA_HTTP_HEADERS MAP {'Authorization': 'Bearer ' || getenv('LUMID_TOKEN')}
);

-- Envelope route: unwrap the `bars` key to get one row per bar.
SELECT unnest(bars) AS b
FROM read_json_auto('https://lum.id/findata/ohlc/AAPL?interval=1d');

-- Bare-array route: already one row per record, no unnest.
SELECT published_at, publisher, headline
FROM read_json_auto('https://lum.id/findata/news/search?q=guidance+cut&limit=500');

-- Join two endpoints in one query.
WITH tech AS (
  SELECT unnest(hits) AS h
  FROM read_json_auto('https://lum.id/findata/screener?sector=Technology&limit=50')
)
SELECT h.symbol, h.market_cap FROM tech ORDER BY h.market_cap DESC;

Python — pandas / polars

import os, requests, pandas as pd

S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['LUMID_TOKEN']}"
BASE = "https://lum.id/findata"

def table(path, key=None, **params):
    r = S.get(f"{BASE}{path}", params=params, timeout=60)
    r.raise_for_status()
    body = r.json()
    # bare array, or an envelope whose rows live under `key`
    return pd.DataFrame(body if key is None else body[key])

bars = table("/ohlc/AAPL", "bars", interval="1d")
news = table("/news/search", q="guidance cut", limit=500)
# 429 → back off; the budget is in r.headers["x-ratelimit-remaining"].

Shell / anything else

jq for the envelope, then feed whatever you like — duckdb, csvkit, R's jsonlite, Excel's Get Data → From Web (add the header under Advanced), or a Grafana JSON datasource.
curl -sH "Authorization: Bearer $LUMID_TOKEN" \
  "https://lum.id/findata/prediction-markets/trades/kalshi/<ticker>?limit=1000" \
  | jq -r '.[] | [.ts,.price,.size] | @csv' > trades.csv

Working within the limits. List endpoints take limit (max 1000) and offset — page rather than asking for everything. /ohlc ignores limit and applies a server-side row cap; narrow with from / to instead. Watch x-ratelimit-remaining and honour Retry-After on a 429. For bulk or recurring pulls, or a direct Postgres connection for a BI tool, ask — those are provisioned per-account rather than open to anonymous scraping.