# Using FinData OS from a Claude Code session (or any shell)

**Key**: `~/Desktop/Cluster/secrets/findata/api-key-claude-code.txt` (scopes: read:market, read:fundamentals, query, export, admin;
created 2026-11-02 for the owner's Claude Code sessions). Never paste it into code, docs or chat; the helper reads it.
**Base URL**: https://findata.spboucher.ai (API prefix `/api/v1`, Swagger at `/api/docs`). Auth header: `Authorization: Bearer <key>`.

## Fastest path: the `fdq` helper
```bash
FDQ=~/Desktop/Cluster/projets/findata/scripts/fdq          # laptop mirror; also at M3U96a:~/apps/findata/scripts/fdq
$FDQ health                                               # status, alerts, lake free space, worker, backup age
$FDQ datasets                                             # 64 datasets: id, status, rows, first/last session
$FDQ bars AAPL 1m 2024-03-01 2024-03-31                   # JSON page (<= 10 000 rows/page, 1m <= 31 days per call); raw|split|split_div as 5th arg
$FDQ sql "SELECT session_date, min(low) lo, max(high) hi, sum(volume) v FROM market_bars_stock_1m_raw WHERE symbol='AAPL' AND year=2024 GROUP BY 1 ORDER BY 1"
$FDQ sql "SELECT trade_date, strike, call_put, bid, ask, open_interest, delta FROM options_eod WHERE underlying='SPY' AND trade_date=DATE '2024-03-15' AND expiry=DATE '2024-03-28' ORDER BY strike" 500
$FDQ fund MSFT 2015-01-01T00:00:00Z rev,net_inc,eps_d     # point-in-time: only facts available at as_of
$FDQ export "AAPL,MSFT,NVDA" 2024-01-01 2024-12-31 market_bars.stock.1m.raw /tmp/x.parquet   # large ranges -> async Parquet
$FDQ jobs ; $FDQ enqueue '{"kind":"incremental","params":{"type":"stock","period":"day"}}'  # admin (ingestion queue)
```

## Python (SDK)
```bash
cd ~/Desktop/Cluster/projets/findata
FINDATA_API_KEY=$(cat ~/Desktop/Cluster/secrets/findata/api-key-claude-code.txt) .venv/bin/python my_script.py
```
```python
import os
from findata_sdk import FinData
fd = FinData("https://findata.spboucher.ai", api_key=os.environ["FINDATA_API_KEY"])
bars = fd.bars("AAPL", "1m", "2024-03-01", "2024-03-31")            # pyarrow.Table (all pages, Arrow IPC transport)
df = bars.to_pandas()
tbl = fd.sql("SELECT symbol, count(*) n FROM market_bars_stock_1m_split_div WHERE symbol IN ('AAPL','MSFT') AND year=2020 GROUP BY 1")
facts = fd.fundamentals("AAPL", as_of="2020-01-01T00:00:00Z", metrics=["rev", "net_inc"], period_type="q")
path = fd.export(["AAPL", "MSFT"], "2015-01-01", "2024-12-31", dest="/tmp/aapl_msft_1m.parquet")   # ~2 s per 1 M rows
```

## What is there (SQL view names = dataset id with dots -> underscores)
| View | Content | Partition columns for the fast path |
|---|---|---|
| `market_bars_stock_1m_raw` (+ `_split`, `_split_div`) | US stocks 1-minute, 16 195 symbols incl. `-DELISTED`, 2000 -> today | `symbol`, `year`, `session_date` |
| `market_bars_stock_{5m,30m,1h,1d}_{raw,split,split_div}` | coarser bars (5m raw is derived from 1m; vendor 5m/30m/1h exist only adjusted) | same |
| `market_bars_etf_*` | same structure for 5 161 ETFs | same |
| `market_bars_index_{1m,5m,30m,1h,1d}_raw` | 122 indices (no volume) | same |
| `market_bars_fx_*_raw`, `market_bars_crypto_*_raw` | FX majors (volume = tick count), crypto (UTC) | same |
| `market_bars_futures_{tf}_continuous_{raw,ratio,absolute}` | continuous series per root (ES, NQ, CL...) | `symbol`, `year` |
| `market_bars_futures_contracts_{tf}_raw` | individual contracts, symbol = `ROOT_MYY` (e.g. `ES_H25`) | `symbol`, `year` |
| `options_eod` | EOD chains 2010 -> today, 11 582 underlyings, IV + Greeks | `underlying`, `period` (`2024q1`, `latest`), `trade_date` |

Bars columns: `instrument_id, symbol_as_reported, asset_class, interval, timestamp_utc (bar OPEN, UTC), session_date, open, high, low, close, volume, currency, trade_count, vwap, adjustment_type, source_id, ingested_at, quality_flags, revision_id`.
Fundamentals live in Postgres (not in SQL views): use `/api/v1/fundamentals/{ticker}` (as_of semantics) — 5 451 entities, 76 metrics (`rev, net_inc, eps_d, assets_tot, cash_op, shares, roe` ...).

## Performance rules (measured on the full lake)
- Put `symbol='X'` / `symbol IN (...)` (or `underlying='X'`) and ideally `year=` or a date range in every SQL statement -> 30-300 ms. Without them the view is a directory scan of up to 320 k files (30-60 s, may hit the 30 s timeout).
- Cross-sections: use `market_bars_stock_1d_raw WHERE session_date = DATE '...'` (about 1.3 s) or a `session_date =` predicate on 1m (about 3 s).
- REST bars endpoint: 1m <= 31 days per call, 5m <= 186 days, 1d <= 10 years; pages of <= 10 000 rows with `next_cursor`; larger ranges -> `POST /exports` (Parquet, dataset version pinned).
- Rate limit 600 req/min per key. Responses carry `X-Request-ID` and `X-Dataset-Version`.

## Operations (admin scope)
`fdq jobs`, `fdq enqueue '{...}'` (kinds: incremental, backfill, derive, compaction, fundamentals, options, backup, quality, gc), `fdq get /api/v1/admin/storage`, `fdq get /api/v1/quality`. Full operator notes: `docs/OPERATIONS.md`. License: FirstRate Data private use — never republish raw bars/tables.