# findata API — usage guide Base URL: `https://kv.run:5000` · All data routes require auth. ## Start here New to the API? Open these in a browser (no auth needed): - **`https://kv.run:5000/`** — landing page: quickstart, auth, and the endpoint map. - **`https://kv.run:5000/reference`** — browsable API reference (ReDoc, generated from the live spec). - **`https://kv.run:5000/openapi.json`** — OpenAPI 3.1 spec (import into Postman / generate a client). - **`https://kv.run:5000/llm`** — LLM proxy quickstart. - **`https://kv.run:5000/status`** / **`/usage`** — health board + global usage dashboard. Then get a token (a Lumid PAT) and call any data route with `Authorization: Bearer `. ## Auth Send a bearer token on every data route: ``` Authorization: Bearer ``` - A **Lumid PAT** (`lm_pat_live_…`) or an internal **local key** (`LUMID_API_KEYS`). - Missing/invalid → `401`. Over rate limit → `429` with `Retry-After`. - Rate-limit headers on every response: `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset`. - **Public (no auth):** `/`, `/reference`, `/openapi.json`, `/llm`, `/usage.md`, `/skill.md`, `/status`, `/usage`, `/freshness`, `/health`, `/docs`, `/redoc`. ## Conventions Date/time filters (`start`/`end`, `from`/`to`, `since`/`until`) accept **RFC3339** (`2026-05-16T00:00:00Z`) or bare **`YYYY-MM-DD`** (→ `00:00:00 UTC`). Comma-separated list params (`symbols=`, `ticker=`) take multiple values in one call. Symbols are upper-cased server-side. Responses carry `ETag` + `Cache-Control`; send `If-None-Match` for `304`. ```bash H='Authorization: Bearer ' ``` --- ## Prices & OHLC ### Live quotes ```bash curl -H "$H" "https://kv.run:5000/quotes?symbols=AAPL,MSFT,BTCUSD" ``` Returns the live streaming tick when available (`source` starts with `tier_a:`, `stale:false`). Falls back to the last stored bar when the feed is down or market is closed (`stale:true`, `source:"prev_close"` or `source:"last_bar"`). Only symbols with no tick *and* no bar return `price:null, source:"no_cache"`. ```bash curl -H "$H" "https://kv.run:5000/quotes/stream?symbols=AAPL,BTCUSD" # SSE: subscribed, tick, heartbeat curl -H "$H" "https://kv.run:5000/quote-stats/AAPL" # 52w high/low, day range, SMAs ``` ### OHLC bars `/ohlc/:symbol?interval=<1min|5min|15min|30min|1hour|4hour|1d>&from=&to=` Valid intervals: `1min 5min 15min 30min 1hour 4hour 1d`. `daily`/`day`/`1d` variants other than exactly `1d` are **invalid**. ```bash curl -H "$H" "https://kv.run:5000/ohlc/AAPL?interval=1d&from=2025-12-01&to=2026-02-01" curl -H "$H" "https://kv.run:5000/ohlc/BTCUSD?interval=1h" # non-equity rolled up from 1-min on the fly curl -H "$H" "https://kv.run:5000/ohlc/EURUSD?interval=5min" # forex ``` Returns `{symbol, interval, count, bars:[{ts,o,h,l,c,v},...]}`. `from`/`to` and `start`/`end` are interchangeable; omit for a default trailing window. US equity OHLC bars (all intervals) are sourced from two independent feeds. The server merges them automatically; coverage continues if one feed has a gap (e.g. bandwidth exhaustion on the primary). Non-equity bars (forex, crypto, indices) use the primary feed only. ### Technical indicators ```bash curl -H "$H" "https://kv.run:5000/technical/AAPL" # all indicators, latest values curl -H "$H" "https://kv.run:5000/technical/AAPL/latest" # same, single-row snapshot ``` Indicators (SMA, EMA, RSI, MACD) are drawn from two independent data sources. Multi-source coverage lets you cross-validate and provides continuity when one source has a data gap. ### Market movers & sector/industry snapshots ```bash curl -H "$H" "https://kv.run:5000/market-movers" # gainers/losers/most-active curl -H "$H" "https://kv.run:5000/market-cap/AAPL/history" # historical market-cap series curl -H "$H" "https://kv.run:5000/sectors/pe" # sector P/E snapshot curl -H "$H" "https://kv.run:5000/sectors/performance" # sector % performance curl -H "$H" "https://kv.run:5000/industries/pe" curl -H "$H" "https://kv.run:5000/industries/performance" ``` --- ## Symbols & universe ```bash curl -H "$H" "https://kv.run:5000/symbols?ticker=AAPL,MSFT,SPY,BTCUSD" # batch metadata, 1 call (max 500) curl -H "$H" "https://kv.run:5000/symbols/AAPL" # single symbol metadata curl -H "$H" "https://kv.run:5000/symbols/search?q=apple" curl -H "$H" "https://kv.run:5000/universe" # full 7,851-symbol roster curl -H "$H" "https://kv.run:5000/universe/actively-trading" # currently active subset curl -H "$H" "https://kv.run:5000/screener?sector=Technology&marketCapMoreThan=1e12&limit=50" ``` Screener params: `sector`, `industry`, `exchange`, `country`, `marketCapMoreThan`/`marketCapLessThan`, `isEtf`, `isFund`, `limit`, `offset`. --- ## Fundamentals ```bash # Latest wide-format row (all statements merged) curl -H "$H" "https://kv.run:5000/fundamentals/AAPL/latest" # Historical statements — statement ∈ income|balance|cashflow curl -H "$H" "https://kv.run:5000/fundamentals/AAPL/history?statement=income&period=quarter&limit=40" curl -H "$H" "https://kv.run:5000/fundamentals/AAPL/history?statement=balance&period=annual" ``` --- ## Analysis ```bash curl -H "$H" "https://kv.run:5000/ratios/AAPL" # P/E, P/B, ROE, margins, … curl -H "$H" "https://kv.run:5000/key-metrics/AAPL" # EV/EBITDA, FCF yield, ROIC, … curl -H "$H" "https://kv.run:5000/metrics-snapshot/AAPL" # point-in-time: 52w stats, beta, returns curl -H "$H" "https://kv.run:5000/financial-scores/AAPL" # Altman Z, Piotroski F, custom scores curl -H "$H" "https://kv.run:5000/earnings-quality/AAPL" # accruals, cash conversion curl -H "$H" "https://kv.run:5000/enterprise-value/AAPL" # EV series curl -H "$H" "https://kv.run:5000/owner-earnings/AAPL" # Buffett-style owner earnings curl -H "$H" "https://kv.run:5000/dcf/AAPL" # discounted cash-flow model curl -H "$H" "https://kv.run:5000/financial-growth/AAPL" # revenue/EPS/FCF growth rates curl -H "$H" "https://kv.run:5000/income-statement-growth/AAPL" curl -H "$H" "https://kv.run:5000/balance-sheet-growth/AAPL" curl -H "$H" "https://kv.run:5000/cash-flow-growth/AAPL" ``` --- ## Estimates ```bash curl -H "$H" "https://kv.run:5000/grades/AAPL" # analyst buy/hold/sell grades curl -H "$H" "https://kv.run:5000/estimates/AAPL/price-target" # price target history curl -H "$H" "https://kv.run:5000/analyst-estimates/AAPL" # consensus EPS/revenue estimates curl -H "$H" "https://kv.run:5000/recommendation/AAPL" # upgrade/downgrade history ``` --- ## Ownership & investors ```bash curl -H "$H" "https://kv.run:5000/holders/AAPL/top" # top 13F holders curl -H "$H" "https://kv.run:5000/insider/AAPL/transactions" # insider buys/sells curl -H "$H" "https://kv.run:5000/insider/AAPL/sentiment" # net insider sentiment curl -H "$H" "https://kv.run:5000/insider/AAPL/statistics" # insider stats summary curl -H "$H" "https://kv.run:5000/fund-ownership/AAPL" # mutual/ETF fund holders curl -H "$H" "https://kv.run:5000/funds-disclosure/AAPL" # Form-D / fund disclosures curl -H "$H" "https://kv.run:5000/gov-trades/AAPL" # congressional trades curl -H "$H" "https://kv.run:5000/acquisitions/AAPL" # beneficial ownership (13D/G) # Institutional analytics (by CIK) curl -H "$H" "https://kv.run:5000/institutional/AAPL/holders/analytics" curl -H "$H" "https://kv.run:5000/institutional/holder//dates" curl -H "$H" "https://kv.run:5000/institutional/holder//performance" curl -H "$H" "https://kv.run:5000/institutional/holder//industries" curl -H "$H" "https://kv.run:5000/institutional/industries" ``` --- ## Company metadata ```bash curl -H "$H" "https://kv.run:5000/executives/AAPL" # C-suite + board curl -H "$H" "https://kv.run:5000/governance/AAPL/compensation" # exec compensation curl -H "$H" "https://kv.run:5000/exec-comp-benchmark/" # industry avg comp benchmarks curl -H "$H" "https://kv.run:5000/peers/AAPL" # peer companies curl -H "$H" "https://kv.run:5000/supply-chain/AAPL" # supply-chain relationships curl -H "$H" "https://kv.run:5000/shares-float/AAPL" # float, short interest curl -H "$H" "https://kv.run:5000/employee-count/AAPL" # historical headcount curl -H "$H" "https://kv.run:5000/symbol-changes" # ticker rename history curl -H "$H" "https://kv.run:5000/symbol/SPY/etf-exposure" # ETF exposure for a symbol ``` --- ## Events & calendars ```bash curl -H "$H" "https://kv.run:5000/earnings" # earnings calendar (upcoming) curl -H "$H" "https://kv.run:5000/earnings/AAPL/history" # per-symbol earnings history curl -H "$H" "https://kv.run:5000/transcripts/AAPL" # earnings call transcripts (list) curl -H "$H" "https://kv.run:5000/transcripts/AAPL/2025/4" # specific quarter transcript curl -H "$H" "https://kv.run:5000/ipos" # IPO calendar curl -H "$H" "https://kv.run:5000/dividends/AAPL" # dividend history curl -H "$H" "https://kv.run:5000/dividends-calendar" # upcoming dividend dates curl -H "$H" "https://kv.run:5000/splits/AAPL" # split history curl -H "$H" "https://kv.run:5000/splits-calendar" # upcoming splits curl -H "$H" "https://kv.run:5000/fda-calendar" # FDA PDUFA / advisory dates curl -H "$H" "https://kv.run:5000/mergers-acquisitions" # M&A deal tracker curl -H "$H" "https://kv.run:5000/exchange-market-hours" # exchange open/close windows curl -H "$H" "https://kv.run:5000/exchange/XNYS/holidays" # exchange holidays ``` --- ## ETF ```bash curl -H "$H" "https://kv.run:5000/etf/SPY/info" # fund info, AUM, expense ratio curl -H "$H" "https://kv.run:5000/etf/SPY/holdings" # top holdings curl -H "$H" "https://kv.run:5000/etf/SPY/sector-weightings" # sector allocation curl -H "$H" "https://kv.run:5000/etf/SPY/country-weightings" # country allocation curl -H "$H" "https://kv.run:5000/index/SPX/constituents" # index constituent list ``` --- ## News ~20 M articles across multiple wire and CSV feeds, deduplicated, full-text indexed. A sentiment-enhanced feed adds structured per-ticker sentiment (positive/negative/neutral + reasoning text) for each article; stored in the `raw` field and refreshed every 4 hours. ```bash curl -H "$H" "https://kv.run:5000/news/AAPL?limit=50" # per-symbol news curl -H "$H" "https://kv.run:5000/news/latest?since=2026-06-01&limit=100" # global firehose curl -H "$H" "https://kv.run:5000/news/search?q=earnings+beat&limit=50" # full-text search curl -H "$H" "https://kv.run:5000/news/stats" # article counts / source breakdown curl -H "$H" "https://kv.run:5000/news/social-sentiment/AAPL" # social sentiment series curl -H "$H" "https://kv.run:5000/news/symbol-sentiment/AAPL" # symbol-level sentiment ``` --- ## KOL tweets 33.8 M tweets from curated handles, 2010–2026. Full-text + cashtag indexed. ```bash curl -H "$H" "https://kv.run:5000/kols" # roster list curl -H "$H" "https://kv.run:5000/kols/tweets?limit=50" # recent tweets, all handles curl -H "$H" "https://kv.run:5000/kols/tweets/search?q=earnings+beat&limit=50" # full-text search curl -H "$H" "https://kv.run:5000/kols/tweets/search?q=NVDA&cashtag=NVDA" # cashtag filter curl -H "$H" "https://kv.run:5000/kols/tweets/by-symbol/AAPL" # tweets mentioning $AAPL curl -H "$H" "https://kv.run:5000/kols/tweets/by-symbol/AAPL/history?limit=200" # historical curl -H "$H" "https://kv.run:5000/kols/elonmusk/tweets" # per-handle recent curl -H "$H" "https://kv.run:5000/kols/elonmusk/tweets/history?since=2025-01-01" # per-handle archive curl -H "$H" "https://kv.run:5000/kols/archive/stats" # archive row counts ``` ### KOL media (7.8 M mirrored images) ```bash curl -H "$H" "https://kv.run:5000/kols/media" # media index curl -H "$H" -L "https://kv.run:5000/kols/media/by-url?u=" # serve by original CDN URL; falls through if not cached curl -H "$H" "https://kv.run:5000/kols/media/" # serve by internal path ``` --- ## Macro ```bash curl -H "$H" "https://kv.run:5000/macro/treasury-rates" # yield curve history curl -H "$H" "https://kv.run:5000/macro/economic-indicators" # CPI, unemployment, GDP, … curl -H "$H" "https://kv.run:5000/macro/economic-calendar?from=2026-01-01&to=2026-12-31" curl -H "$H" "https://kv.run:5000/macro/cot/ES" # CFTC commitment of traders ``` --- ## Short interest & short volume FINRA bi-weekly short interest and daily off-exchange short volume per symbol. Updated weekly. ```bash curl -H "$H" "https://kv.run:5000/short-interest/AAPL" # FINRA short interest history (settlement_date, short_interest, avg_daily_volume, days_to_cover) curl -H "$H" "https://kv.run:5000/short-interest/AAPL?limit=10" # last 10 bi-weekly prints curl -H "$H" "https://kv.run:5000/short-volume/AAPL" # daily off-exchange short volume (ADF + Nasdaq Carteret + NYSE breakdowns) ``` --- ## SEC filings — text Machine-readable SEC risk-factor disclosures and plain-text 10-K sections, updated weekly. ```bash # Risk factors — standardized taxonomy (primary/secondary/tertiary category + supporting text) curl -H "$H" "https://kv.run:5000/risk-factors/AAPL" curl -H "$H" "https://kv.run:5000/risk-factors/AAPL?limit=50" # 10-K annual filing sections (business, risk_factors, mda, legal_proceedings, …) curl -H "$H" "https://kv.run:5000/10k-sections/AAPL" curl -H "$H" "https://kv.run:5000/10k-sections/AAPL?section=mda" # management's discussion curl -H "$H" "https://kv.run:5000/10k-sections/AAPL?section=risk_factors" # risk factor text ``` --- ## Regulatory ```bash curl -H "$H" "https://kv.run:5000/esg/AAPL/disclosures" # ESG disclosure filings curl -H "$H" "https://kv.run:5000/esg/AAPL/ratings" # third-party ESG ratings curl -H "$H" "https://kv.run:5000/esg/AAPL/historical" # historical ESG time-series curl -H "$H" "https://kv.run:5000/filings/AAPL" # SEC filings (10-K, 10-Q, 8-K, …) curl -H "$H" "https://kv.run:5000/xbrl/AAPL/filings" # XBRL filing index curl -H "$H" "https://kv.run:5000/xbrl/AAPL/filing/" # XBRL filing detail curl -H "$H" "https://kv.run:5000/lobbying/AAPL" # lobbying spend history curl -H "$H" "https://kv.run:5000/usa-spending/AAPL" # federal contract awards curl -H "$H" "https://kv.run:5000/visa-applications/AAPL" # H-1B / LCA visa applications curl -H "$H" "https://kv.run:5000/uspto-patents/AAPL" # patent grants ``` --- ## Prediction markets `venue` ∈ `polymarket | kalshi` · `market_id` = polymarket **condition_id** (`0x…`) or kalshi **ticker** ```bash # Discovery curl -H "$H" "https://kv.run:5000/prediction-markets/markets/search?q=bitcoin" curl -H "$H" "https://kv.run:5000/prediction-markets/events?status=open&limit=100" curl -H "$H" "https://kv.run:5000/prediction-markets/markets/polymarket/" curl -H "$H" "https://kv.run:5000/prediction-markets/markets/kalshi/" # Price history (OHLC — UNION of executed trades + orderbook midprice) # interval is integer minutes: 1|5|15|60|1440 # Polymarket coverage: interval=1440 (daily) back to 2024-01-02; intervals ≤60 only from ~Dec 2025. # For any market older than ~7 months, use interval=1440. Kalshi: all intervals back to 2021-06. curl -H "$H" "https://kv.run:5000/prediction-markets/candles/polymarket/?interval=60" curl -H "$H" "https://kv.run:5000/prediction-markets/candles/kalshi/?interval=60" # Trade history curl -H "$H" "https://kv.run:5000/prediction-markets/trades/polymarket/" curl -H "$H" "https://kv.run:5000/prediction-markets/trades/kalshi/" # Orderbook (latest L2 snapshot) curl -H "$H" "https://kv.run:5000/prediction-markets/orderbook/polymarket/" curl -H "$H" "https://kv.run:5000/prediction-markets/orderbook/kalshi/" # Market analytics curl -H "$H" "https://kv.run:5000/prediction-markets/open-interest/polymarket/" curl -H "$H" "https://kv.run:5000/prediction-markets/top-holders/polymarket/" curl -H "$H" "https://kv.run:5000/prediction-markets/matched-pairs/polymarket/" # cross-venue equivalents # Leaderboard — window ∈ 7d|24h|30d|week|all curl -H "$H" "https://kv.run:5000/prediction-markets/leaderboard?window=7d&venue=polymarket&limit=50" # Wallet (Polymarket) curl -H "$H" "https://kv.run:5000/prediction-markets/wallet/
" curl -H "$H" "https://kv.run:5000/prediction-markets/wallet/
/pnl" curl -H "$H" "https://kv.run:5000/prediction-markets/wallet/
/positions" curl -H "$H" "https://kv.run:5000/prediction-markets/wallet/
/activity" ``` Note: `event_id` is a **string** (`"284199"`), not an integer. Kalshi is accepted on most endpoints but wallet/leaderboard data is Polymarket-only. --- ## Realtime (SSE / WebSocket) ```bash # SSE streams (no reconnect needed — server sends heartbeat every 30 s) curl -N -H "$H" "https://kv.run:5000/quotes/stream?symbols=AAPL,BTCUSD" # tick: subscribed|tick|heartbeat curl -N -H "$H" "https://kv.run:5000/prediction-markets/stream" # PM: trade + orderbook deltas ``` **WebSocket** — auth via `Authorization` header, `?token=`, or `Sec-WebSocket-Protocol: bearer.`: - `wss://kv.run:5000/ws/quotes` — market ticks (subscribe `{symbols:[...]}` after connect) - `wss://kv.run:5000/ws/news` — news article stream - `wss://kv.run:5000/ws/prediction-markets` — PM events (same as the PM SSE) US equity quotes are delivered from the primary tick stream with a secondary quote feed as a live backup — the server auto-covers from the secondary within seconds if the primary goes quiet, with no manual intervention required. PM event shape: ```jsonc // Polymarket trade {"channel":"trade","venue":"polymarket","asset_id":"…","condition_id":"0x…","price":"0.62","size":"40","side":"BUY"} // Polymarket orderbook delta {"channel":"orderbook","venue":"polymarket","asset_id":"…","condition_id":"0x…", …} // Kalshi trade {"channel":"trade","venue":"kalshi","market_ticker":"KXBTC-…","yes_price_dollars":"0.59","count":"164","taker_side":"yes"} ``` SSE optional filters: `?asset_ids=…&condition_ids=…` (Polymarket keys — Kalshi passes through unfiltered). --- ## OpenAI-compatible LLM (`/v1/*`) The service proxies to a reasoning model. Point any OpenAI or Anthropic SDK at this host and use your Lumid PAT as the API key. ```python from openai import OpenAI client = OpenAI(base_url="https://kv.run:5000/v1", api_key="") resp = client.chat.completions.create( model="", # or omit for the default messages=[{"role":"user","content":"Summarize AAPL's latest quarter."}], max_tokens=1024, ) print(resp.choices[0].message.content) ``` ```bash curl https://kv.run:5000/v1/models -H "$H" # list available models curl https://kv.run:5000/v1/chat/completions -H "$H" \ -H 'Content-Type: application/json' \ -d '{"model":"","messages":[{"role":"user","content":"hi"}]}' ``` Endpoints: `/v1/chat/completions`, `/v1/completions`, `/v1/embeddings`, `/v1/models`, `/v1/messages`, `/v1/messages/count_tokens`. **Reasoning models**: thinking lands in `reasoning_content` (OpenAI shape) or a `thinking` block (Anthropic shape). Set `max_tokens` ≥ a few hundred or `content` may be empty. Returns `503` if no LLM backend is configured. --- ## MCP (Model Context Protocol) `POST /mcp` — JSON-RPC 2.0, Streamable-HTTP transport (MCP 2025-03-26). 92 auto-generated tools, one per read endpoint. ```bash curl -H "$H" -H 'Content-Type: application/json' -X POST https://kv.run:5000/mcp \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' curl -H "$H" -H 'Content-Type: application/json' -X POST https://kv.run:5000/mcp \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fundamentals_latest","arguments":{"symbol":"AAPL"}}}' ``` --- ## Write / ingest ```bash # Write rows to an existing table (validated, provenance-stamped, upserted) curl -H "$H" -H 'Content-Type: application/json' \ -X POST https://kv.run:5000/ingest// \ -d '{"records":[{"symbol":"AAPL","date":"2026-06-01", ...}]}' ``` Provenance fields (`source`, `source_endpoint`, `source_run_id`, `ingest_ts`) are stamped server-side — don't supply them. Upsert is newest-wins on the natural key; re-POSTing identical rows is a no-op. Other ingest modes: `/ingest//
/stream` (NDJSON chunked), `/ingest//
/file` (multipart JSON/CSV/Parquet), `/ingest/blob` (binary / images with sha256 dedup), `/ingest/adapter/` (upstream-shape records, 69 adapters). ### Schema negotiation (new table) POST to an unknown table → platform suggests a schema and stages a **proposal**: ```bash curl -H "$H" -H 'Content-Type: application/json' -X POST https://kv.run:5000/ingest/sandbox/widgets \ -d '{"records":[{"widget_id":7,"name":"alpha","price":9.99,"ts":"2026-06-01T00:00:00Z"}]}' # returns proposal_id; then negotiate: curl -H "$H" https://kv.run:5000/catalog/ingress/proposals/ curl -H "$H" -X POST https://kv.run:5000/ingress/proposals//approve ``` --- ## Catalog & lineage ```bash curl -H "$H" "https://kv.run:5000/catalog/schemas" curl -H "$H" "https://kv.run:5000/catalog/schemas//tables" curl -H "$H" "https://kv.run:5000/catalog/tables//
" curl -H "$H" "https://kv.run:5000/catalog/tables//
/schema.json" curl -H "$H" "https://kv.run:5000/catalog/lineage/run/" curl -H "$H" "https://kv.run:5000/catalog/lineage/row?schema=market&table=ohlc_daily&symbol=AAPL" curl -H "$H" "https://kv.run:5000/catalog/lineage/runs" curl -H "$H" "https://kv.run:5000/catalog/sources" curl -H "$H" "https://kv.run:5000/catalog/submitters" ``` --- ## Your usage & status ```bash curl -H "$H" "https://kv.run:5000/usage/me" # your calls, bytes, hourly breakdown ``` Returns `{sub, total_calls, bytes_out, calls_last_24h, hourly_last_24h:[24 hourly buckets]}`. `/status` (HTML health board), `/freshness` (per-endpoint SLA counts), `/health` (liveness probe). All public, no auth.