Skip to main content
Run ad-hoc or saved SQL statements against the ClickHouse warehouse. This endpoint powers the in-product SQL editor and programmatic integrations.
Requests are rate limited to 30 executions per minute per authenticated user or API key.

​
Request fields

​
query
string
Raw SQL to execute. Mutually exclusive with query_id.
​
query_id
string
Execute a saved query stored in Supabase. Ignored when query is supplied.
​
limit
integer
default:"None"
Optional row limit override. Useful when running saved queries with large defaults.

​
Saved query execution

When you provide query_id, the service fetches the latest SQL from Supabase before execution. Use this flow to keep complex statements version-controlled while reusing the same API call.

​
Response structure

  • result.columns lists column names in order
  • result.data contains an array of rows (each row is an ordered array)
  • result.execution_time_ms reports end-to-end latency
  • query echoes the executed SQL after namespace rewriting
Track execution analytics with GET /api/query//stats or list all saved query metrics via GET /api/queries/stats.

​
Example Response

{
  "success": true,
  "result": {
    "columns": ["title", "yes_probability", "volume_24hr"],
    "data": [
      ["Will Bitcoin hit $100k in 2025?", 0.67, 284567.23],
      ["AI regulation passes before 2026", 0.52, 156234.89],
      ["Trump wins 2024 election", 0.48, 1245678.90]
    ],
    "row_count": 3,
    "execution_time_ms": 89,
    "statistics": {
      "elapsed": 0.086,
      "rows_read": 56519
    }
  },
  "query": "SELECT title, yes_probability, volume_24hr FROM polymarket_events ORDER BY volume_24hr DESC LIMIT 3"
}

​
Validate before running

Use POST /api/query/validate to confirm syntax and inspect ClickHouse EXPLAIN output without incurring compute.