# Historical SQL Quickstart

> Run a bounded, authenticated Historical SQL request against RawOptionTrades and recover safely from validation, read-limit, or timeout errors.

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:

```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
```

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:

```bash
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`.

![Annotated OptionData historical-data page showing the REST endpoint and full SQL documentation link](/docs/historical-sql-quickstart/historical-query-page-annotated.png)

*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](/docs/historical-option-trades-api) 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

| Status | Meaning | Next action |
|---|---|---|
| `400` | SQL failed the public query guard | Correct the statement or column names |
| `401` | Missing or invalid API key | Check the bearer header |
| `403` | No active/trialing Pro entitlement | Review Billing |
| `422 QUERY_TOO_BROAD` | Server read limits were exceeded | Narrow date, symbol, expiry, or strike filters |
| `422 INVALID_QUERY` | ClickHouse rejected the expression | Correct the reported query problem |
| `429` | Rate limited | Honor `Retry-After` |
| `504` | Query timed out | Split the request into smaller windows |

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