# Warehouse SQL over REST

Send `POST /api/v1/data/games/{gameId}/sql` to the existing Ravensight API with your studio-bound programmatic token in the Authorization header. The JSON body contains `sql` and optional `include_synthetic` (exclude, include or only). The same SELECT-only guard as [run_sql](https://ravensight.io/docs/run-sql/) rewrites every events-table reference to your game. It cannot read another game, other tables, credentials or external URLs. Standard MCP run_sql limits are unchanged.

The warehouse profile allows up to 10,000 result rows, 30 seconds, 1 GB read, one billion scanned rows and a 4 MB response. Each token may start 200 warehouse queries per UTC day. An estimate above one billion rows is refused before reservation. Role, project, tool allowlist, prepaid funding and token-cap checks still apply.

**Price:** `(2 + ceil(rows read / 500000)) × 100000` weighted events. Before execution, Ravensight estimates the guarded scan and reserves that amount. If actual scanning uses fewer calls, the difference is refunded once; a larger actual scan never increases the reservation. When actual row statistics are unavailable, the reservation is retained and the response says so. Refused execution is refunded. Use the same `X-Ravensight-Operation-Id` on identical retries to reuse the stored result and charge.

| Rows read | Calls | Weighted events | After included events |
| --- | --- | --- | --- |
| 0 | 2 | 200,000 | $0.10 |
| 500,000 | 3 | 300,000 | $0.15 |
| 1,200,000 | 5 | 500,000 | $0.25 |

```
{ "sql": "SELECT event_name, count() AS events FROM events GROUP BY event_name ORDER BY events DESC LIMIT 20", "include_synthetic": "exclude" }
```

The response includes scanned rows, the estimate, reserved and charged calls, and normal operation metadata. Audit rows record IDs and scan counts, excluding SQL text. [OpenAPI specification](https://ravensight.io/docs/openapi/data-v1.json).

Source: https://ravensight.io/docs/warehouse-sql/
Last updated: 2026-11-15
