Execute SQL Query
POST/sql/:sqlID/execute
Run a saved query. Every body field is optional: a bare POST with an empty body runs the saved query with its stored defaults and the cache enabled. Applies a per-query soft rate cap (rate_limit_rpm, clamped to the plan's hard cap) checked before the per-profile hard cap (rpm_sql_execute); cache hits are charged against a separate cached-read ceiling (rpm_sql_execute_cached).
Authentication accepts either a Profile Token (runs the query directly as its owning profile) or an Access-Management-granted analysis / Run-user token (the token must be granted the execute action on the query by id or tag; the query then runs as its owning profile). The grant authorizes execution, not filtering.
Request
Responses
- 200
- 400
- 402
- 403
- 404
- 408
- 429
Query result envelope.
SQL validation error, inactive query, missing/invalid param, a written LIMIT above the plan row cap, a result exceeding the row cap ("Result exceeds the N-row limit. Add LIMIT (and OFFSET to paginate)."), or a device_data_by_tag fan-out rule violation (missing variable/time filter, a time bound beyond the plan's fan-out window, or a tag filter matching more devices than the plan cap).
Plan limit exceeded.
Authorization denied. The analysis or Run-user token has no Access Management policy granting the execute action on this query.
Saved query not found (or not owned by your profile).
Query exceeded the plan statement timeout (e.g. Query timed out (15s limit)).
Rate limit exceeded (soft cap, hard cap, cached-read ceiling, or single-flight wait timeout). Includes a Retry-After header.