# FinData OS — API quick start

Base URL: https://findata.spboucher.ai/api/v1 · OpenAPI: /api/v1/openapi.json · Swagger UI: /api/docs Auth: Authorization: Bearer fd_<prefix>.<secret> (create keys in the console → API keys). Browser sessions use the cookie + X-CSRF-Token. Conventions: UTC ISO-8601 (Z), bars stamped at bar open, cursor pagination (next_cursor), structured errors {"error":{"code","message","request_id"}}, response headers X-Request-ID, X-Dataset-Id, X-Dataset-Version.

K=fd_xxx.yyy
curl -s -H "Authorization: Bearer $K" https://findata.spboucher.ai/api/v1/catalog/datasets | jq '.data[] | {id,status,license_class}'
curl -s -H "Authorization: Bearer $K" "https://findata.spboucher.ai/api/v1/market/bars?symbol=AAPL&interval=1m&start=2026-10-30&end=2026-10-30&limit=5" | jq .
curl -s -H "Authorization: Bearer $K" "https://findata.spboucher.ai/api/v1/fundamentals/AAPL?as_of=2025-01-01T00:00:00Z&metrics=rev,net_inc" | jq '.data[0], .meta'
curl -s -H "Authorization: Bearer $K" -H 'Content-Type: application/json' -d '{"sql":"SELECT symbol_as_reported, count(*) FROM market_bars_stock_1m_raw GROUP BY 1 ORDER BY 2 DESC LIMIT 5"}' https://findata.spboucher.ai/api/v1/query | jq .rows
curl -s -H "Authorization: Bearer $K" -H 'Content-Type: application/json' -d '{"dataset_id":"market_bars.stock.1m.raw","symbols":["AAPL","MSFT"],"start":"2026-10-01","end":"2026-10-30"}' https://findata.spboucher.ai/api/v1/exports   # 202 → poll /exports/{id} → /download

Python SDK (packages/python-sdk, pip install -e packages/python-sdk):

from findata_sdk import FinData
fd = FinData("https://findata.spboucher.ai", api_key="fd_xxx.yyy")
bars = fd.bars("AAPL", "1m", "2026-10-26", "2026-10-30")        # pyarrow.Table (Arrow IPC pages)
df = bars.to_pandas()
path = fd.export(["AAPL", "MSFT"], "2024-01-01", "2026-10-30")     # async Parquet export → local file
facts = fd.fundamentals("AAPL", as_of="2025-01-01T00:00:00Z", metrics=["rev", "eps_d"])

Limits: 1m bars ≤ 31 days per call (5m ≤ 186 d, 1d ≤ 10 y), ≤ 10 000 rows per page → use exports for larger ranges. Query playground: one read-only statement, 30 s, ≤ 100 000 rows. Rate limit 600 req/min per key (configurable per key). License: FirstRate Data private use — do not redistribute raw data.

# SQL playground performance rules (full lake)

• Always filter on symbol = 'X' / symbol IN (...) (bars) or underlying = 'X' (options), optionally year = 2024 or a session_date / trade_date range: the file list is then resolved from the catalog in milliseconds (meta.views_used shows the view name; (full scan) means the slow directory path was used).
• Cross-sectional questions (all symbols on a date): use market_bars_stock_1d_raw (1–2 s) or a session_date = predicate on 1m (≈ 3 s).
• Views carry the partition columns symbol, year (bars) and underlying, period (options) in addition to the data columns.