Historical SQL Quickstart

You are helping me use OptionData (https://www.optiondata.io/), an OPRA-licensed U.S. equity options data API.

Before answering, fetch these public files (no login required) and treat them as the source of truth:
- https://www.optiondata.io/llms.txt — short product map (same content as https://www.optiondata.io/llm.txt)
- https://www.optiondata.io/llms-full.txt — full API reference
- https://www.optiondata.io/openapi.json — HTTP OpenAPI

Do not invent endpoints, fields, tables, or limits. Prefer `Authorization: Bearer apikey_…` for HTTP APIs. Realtime uses `wss://ws.optiondata.io` with a `token` query parameter.

Products:
- Realtime trades WebSocket: wss://ws.optiondata.io
- Historical SQL: POST https://www.optiondata.io/api/historical/sql
- Option chain: POST https://www.optiondata.io/api/option-chain
- Market structure: GET https://www.optiondata.io/api/v1/market-structure/{symbol}

I am asking about: Historical SQL Quickstart
- Markdown: https://www.optiondata.io/md/historical-sql-quickstart/
- HTML docs: https://www.optiondata.io/docs/historical-sql-quickstart/

My question:

Historical SQL accepts read-only SELECT queries over HTTPS. The endpoint applies server-owned row, byte, and execution-time limits, and every visible trade is delayed by at least 15 minutes.

1. Start with a bounded query

This query filters by trading date and symbol, selects explicit columns, and limits output:

SELECT date, time, symbol, put_call, strike, expiration_date, size, price, bid, ask
FROM RawOptionTrades
WHERE date = (SELECT max(date) FROM RawOptionTrades)
  AND symbol = 'AAPL'
ORDER BY time DESC
LIMIT 20

Filtering by date and symbol helps ClickHouse prune work. LIMIT caps returned rows, while OptionData's server-enforced read limits bound the scan itself.

2. Send the request

Store the key in OPTIONDATA_API_KEY, then use the canonical bearer header:

curl -X POST https://www.optiondata.io/api/historical/sql \
  -H "Authorization: Bearer $OPTIONDATA_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "sql=SELECT date, time, symbol, put_call, strike, expiration_date, size, price, bid, ask FROM RawOptionTrades WHERE date = (SELECT max(date) FROM RawOptionTrades) AND symbol = 'AAPL' ORDER BY time DESC LIMIT 20"

A successful response has status: "SUCCESS", a data array, and entitlement/limit information in meta.

Start from the documented REST endpoint, then use the bounded query shown below.

Trial responses are capped at 10 rows even when the SQL uses a larger LIMIT.

3. Keep queries safe

• Query only published, whitelisted tables and columns.
• Filter by date and symbol before widening the request.
• Select only the columns you need.
• Include a reasonable LIMIT.
• Do not include semicolons, SQL comments, mutations, UNION, or query-level SETTINGS.

The public Historical Option Trades API reference is the schema source of truth for this restricted endpoint; system-table discovery is not part of the customer query surface.

4. Recover from errors

Avoid repeatedly retrying the same broad query. Narrow it first.