Execute a SQL query against your analytics data (experimental)

⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet. Runs a single ClickHouse SELECT (or WITH … SELECT) against your organization's analytics views. Before writing a query, call `getAnalyticsSchema` (GET /schema) for the available views and columns, and `getSignalsMetadata` (GET /signals/metadata) for the JSON paths inside `fact_signal.data`. Results are automatically scoped to your organization — no org filter is needed or possible. Only SELECT/WITH statements are accepted. Conventions: monetary amounts are minor units (cents — divide by 100 for the major unit); most are integers, but `fact_cost.cost_amount` is fractional cents (Decimal) since a single AI call usually costs less than a cent; 64-bit integers (counts, ids, amounts) are returned as JSON strings to preserve precision, so parse them client-side. Query signal payloads via JSON paths, e.g. `SELECT data.country::String AS country, count() FROM fact_signal GROUP BY country`. Limits: 30 seconds of execution time and 10,000 result rows (truncation is flagged via `meta.truncated`). Prefer aggregates and a `created_at` date filter on large tables — this endpoint is for interactive analytics, not bulk export.

Authentication

AuthorizationBearer
API Key authentication using Bearer token

Request

Body
querystringRequired1-20480 characters

A single ClickHouse SELECT (or WITH … SELECT) statement against the analytics views. Results are automatically scoped to your organization. See GET /schema for the available views and columns.

Response

200
columnslist of objects
rowslist of lists of any

Result rows; values are ordered to match columns. 64-bit integers (UInt64/Int64 — counts, sums, amounts in cents, ids) are returned as JSON strings to preserve precision; parse them client-side as needed.

metaobject

Errors

400
Bad Request Error
403
Forbidden Error
408
Request Timeout Error
429
Too Many Requests Error
500
Internal Server Error