Execute an analytics query
POST /v1/query
Execute a SQL-like analytics query against telemetry data stored in ClickHouse.
Only SELECT statements are allowed. Queries are validated, rewritten to enforce
tenant isolation, and executed against a read-only connection.
Requires the data:admin scope.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The project ID to query.
SQL query (SELECT only).
Maximum number of rows to return.
Responses
Section titled “ Responses ”Query results.
object
object
Result rows; each object maps column name to value.
object
Number of rows returned.
Headers
Section titled “Headers ”Maximum number of requests allowed per hour.
Number of requests remaining in the current window.
Unix timestamp when the rate limit window resets.
Rejected query. Returned for a malformed request body and for user SQL that the database rejects (unknown column, table, or function; syntax errors; type mismatches; forbidden operations). The ClickHouse diagnostic is included in the error message.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Missing or invalid API key.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
API key with data:admin scope required.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Rate limit exceeded.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Headers
Section titled “Headers ”Maximum number of requests allowed per hour.
Number of requests remaining in the current window.
Unix timestamp when the rate limit window resets.
Number of seconds to wait before retrying. Present only on 429
responses. Because the limit uses a sliding window, honor this value
per response rather than scheduling a retry for the reset time.
Infrastructure failure (for example, the database is unreachable). Errors in the submitted SQL are returned as 400, not 500.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.