curl --request POST \
--url https://api.coval.dev/v1/metrics/sql:test \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"sql_query": "<string>",
"aggregation_method": "<string>",
"unit": "<string>",
"simulation_output_id": "<string>"
}
'import requests
url = "https://api.coval.dev/v1/metrics/sql:test"
payload = {
"sql_query": "<string>",
"aggregation_method": "<string>",
"unit": "<string>",
"simulation_output_id": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sql_query: '<string>',
aggregation_method: '<string>',
unit: '<string>',
simulation_output_id: '<string>'
})
};
fetch('https://api.coval.dev/v1/metrics/sql:test', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coval.dev/v1/metrics/sql:test",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'sql_query' => '<string>',
'aggregation_method' => '<string>',
'unit' => '<string>',
'simulation_output_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coval.dev/v1/metrics/sql:test"
payload := strings.NewReader("{\n \"sql_query\": \"<string>\",\n \"aggregation_method\": \"<string>\",\n \"unit\": \"<string>\",\n \"simulation_output_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.coval.dev/v1/metrics/sql:test")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"sql_query\": \"<string>\",\n \"aggregation_method\": \"<string>\",\n \"unit\": \"<string>\",\n \"simulation_output_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/metrics/sql:test")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sql_query\": \"<string>\",\n \"aggregation_method\": \"<string>\",\n \"unit\": \"<string>\",\n \"simulation_output_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"value": 123,
"unit": "<string>",
"aggregation_method": "<string>",
"row_count": 123,
"subvalues": [
{
"start_offset_seconds": 123,
"end_offset_seconds": 123,
"value": 123
}
],
"error": "<string>",
"simulation_results": [
{
"simulation_output_id": "<string>",
"run_id": "<string>",
"simulation_created_at": "2023-11-07T05:31:56Z",
"value": 123,
"unit": "<string>",
"aggregation_method": "<string>",
"row_count": 123,
"subvalues": [
{
"start_offset_seconds": 123,
"end_offset_seconds": 123,
"value": 123
}
],
"error": "<string>",
"run_display_name": "<string>"
}
],
"requires_simulations": true
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "<string>",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "X-API-Key",
"description": "Invalid or missing API key"
}
]
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "<string>",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "<string>",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error"
}
}{
"error": {
"code": "INTERNAL",
"message": "Service temporarily unavailable",
"details": [
{
"description": "Database routing is temporarily unavailable. Please retry."
}
]
}
}Test a draft SQL metric query
Run a draft SQL Float metric query against simulation data from the
authenticated workspace. By default, the endpoint tests up to ten recent simulations;
provide simulation_output_id to test exactly one simulation. No metric needs to exist
yet and the request makes no changes.
Use GET /v1/metrics/sql-schema to discover the available tables and columns. The query
must return the columns start_offset_milliseconds and value.
Routine authoring failures (invalid SQL, no matching rows) return 200 with a
populated error field rather than an HTTP error; only a malformed request body is a
400.
curl --request POST \
--url https://api.coval.dev/v1/metrics/sql:test \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"sql_query": "<string>",
"aggregation_method": "<string>",
"unit": "<string>",
"simulation_output_id": "<string>"
}
'import requests
url = "https://api.coval.dev/v1/metrics/sql:test"
payload = {
"sql_query": "<string>",
"aggregation_method": "<string>",
"unit": "<string>",
"simulation_output_id": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sql_query: '<string>',
aggregation_method: '<string>',
unit: '<string>',
simulation_output_id: '<string>'
})
};
fetch('https://api.coval.dev/v1/metrics/sql:test', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coval.dev/v1/metrics/sql:test",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'sql_query' => '<string>',
'aggregation_method' => '<string>',
'unit' => '<string>',
'simulation_output_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coval.dev/v1/metrics/sql:test"
payload := strings.NewReader("{\n \"sql_query\": \"<string>\",\n \"aggregation_method\": \"<string>\",\n \"unit\": \"<string>\",\n \"simulation_output_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.coval.dev/v1/metrics/sql:test")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"sql_query\": \"<string>\",\n \"aggregation_method\": \"<string>\",\n \"unit\": \"<string>\",\n \"simulation_output_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/metrics/sql:test")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sql_query\": \"<string>\",\n \"aggregation_method\": \"<string>\",\n \"unit\": \"<string>\",\n \"simulation_output_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"value": 123,
"unit": "<string>",
"aggregation_method": "<string>",
"row_count": 123,
"subvalues": [
{
"start_offset_seconds": 123,
"end_offset_seconds": 123,
"value": 123
}
],
"error": "<string>",
"simulation_results": [
{
"simulation_output_id": "<string>",
"run_id": "<string>",
"simulation_created_at": "2023-11-07T05:31:56Z",
"value": 123,
"unit": "<string>",
"aggregation_method": "<string>",
"row_count": 123,
"subvalues": [
{
"start_offset_seconds": 123,
"end_offset_seconds": 123,
"value": 123
}
],
"error": "<string>",
"run_display_name": "<string>"
}
],
"requires_simulations": true
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "<string>",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "X-API-Key",
"description": "Invalid or missing API key"
}
]
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "<string>",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "<string>",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error"
}
}{
"error": {
"code": "INTERNAL",
"message": "Service temporarily unavailable",
"details": [
{
"description": "Database routing is temporarily unavailable. Please retry."
}
]
}
}Authorizations
API key for authentication
Body
The draft SQL Float metric query to evaluate. Must return the columns
start_offset_milliseconds and value.
How per-row values are aggregated into a single metric value (e.g. MEAN, SUM).
Optional result unit.
Run against this simulation only; omit or send null to use recent workspace simulations.
Response
Query evaluated (check error for authoring failures)
The aggregated metric value, or null when the query produced no value.
Number of rows the query returned for the newest or selected simulation.
Show child attributes
Show child attributes
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.
Results for each recent simulation, or one result when simulation_output_id was provided.
Show child attributes
Show child attributes
Whether simulation data must become available before the query can be tested.
Was this page helpful?