Skip to main content
POST
Test a draft SQL metric query

Authorizations

X-API-Key
string
header
required

API key for authentication

Body

application/json
sql_query
string
required

The draft SQL Float metric query to evaluate. Must return the columns start_offset_milliseconds and value.

aggregation_method
string | null

How per-row values are aggregated into a single metric value (e.g. MEAN, SUM).

unit
string | null

Optional result unit.

simulation_output_id
string | null

Run against this simulation only; omit or send null to use recent workspace simulations.

Response

Query evaluated (check error for authoring failures)

value
number | null

The aggregated metric value, or null when the query produced no value.

unit
string | null
aggregation_method
string | null
row_count
integer

Number of rows the query returned for the newest or selected simulation.

subvalues
object[]
error
string | null

Set when the query could not be evaluated (invalid SQL, missing columns, or no matching rows). Present on a 200 response — routine authoring failures are not HTTP errors.

simulation_results
object[]

Results for each recent simulation, or one result when simulation_output_id was provided.

requires_simulations
boolean

Whether simulation data must become available before the query can be tested.