curl --request POST \
--url https://api.nekt.ai/api/v1/sql-query/ \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"sql": "<string>",
"mode": "csv",
"mode_options": {}
}
'import requests
url = "https://api.nekt.ai/api/v1/sql-query/"
payload = {
"sql": "<string>",
"mode": "csv",
"mode_options": {}
}
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: '<string>', mode: 'csv', mode_options: {}})
};
fetch('https://api.nekt.ai/api/v1/sql-query/', 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.nekt.ai/api/v1/sql-query/",
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' => '<string>',
'mode' => 'csv',
'mode_options' => [
]
]),
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.nekt.ai/api/v1/sql-query/"
payload := strings.NewReader("{\n \"sql\": \"<string>\",\n \"mode\": \"csv\",\n \"mode_options\": {}\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.nekt.ai/api/v1/sql-query/")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"sql\": \"<string>\",\n \"mode\": \"csv\",\n \"mode_options\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nekt.ai/api/v1/sql-query/")
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\": \"<string>\",\n \"mode\": \"csv\",\n \"mode_options\": {}\n}"
response = http.request(request)
puts response.read_body{
"state": "SUCCEEDED",
"presigned_urls": [
"https://storage.googleapis.com/bucket/query-20251119-154427-123456-000000000000.parquet?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=..."
],
"data_scanned_in_bytes": 11250,
"execution_time_in_millis": 408
}SQL Query
Execute a SQL query on the organization’s data warehouse and return presigned URLs to download results.
This endpoint executes SQL queries on the organization’s data warehouse (AWS Athena or GCP BigQuery) and returns presigned URLs for downloading the results directly from cloud storage (S3 or GCS).
Important: Customer data never transits through Nekt servers. Results are stored in the organization’s cloud storage and accessed via time-limited presigned URLs (1 hour expiration).
Requirements:
- Organization must have completed cloud setup (
cloud_setup_completed = True)
Cloud Provider Support:
- AWS: Executes queries on Athena
- GCP: Executes queries on BigQuery
Output Formats:
csv: CSV format (default) - supports simple data types onlyparquet: Parquet format - supports all data types including complex types (arrays, structs, etc.)
Limitations:
- BigQuery CSV export does not support complex data types (ARRAY, STRUCT, JSON). Use Parquet mode instead.
- Athena UNLOAD for Parquet may not support certain timestamp types. Cast problematic columns in the SQL query.
Example Request:
{
"sql": "SELECT * FROM my_table LIMIT 100",
"mode": "parquet",
"mode_options": {"compression": "SNAPPY"}
}
Example Response:
{
"state": "SUCCEEDED",
"presigned_urls": [
"https://storage.googleapis.com/bucket/query-20251119-154427-123456-000000000000.parquet?..."
],
"data_scanned_in_bytes": 11250,
"execution_time_in_millis": 408
}
curl --request POST \
--url https://api.nekt.ai/api/v1/sql-query/ \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"sql": "<string>",
"mode": "csv",
"mode_options": {}
}
'import requests
url = "https://api.nekt.ai/api/v1/sql-query/"
payload = {
"sql": "<string>",
"mode": "csv",
"mode_options": {}
}
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: '<string>', mode: 'csv', mode_options: {}})
};
fetch('https://api.nekt.ai/api/v1/sql-query/', 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.nekt.ai/api/v1/sql-query/",
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' => '<string>',
'mode' => 'csv',
'mode_options' => [
]
]),
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.nekt.ai/api/v1/sql-query/"
payload := strings.NewReader("{\n \"sql\": \"<string>\",\n \"mode\": \"csv\",\n \"mode_options\": {}\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.nekt.ai/api/v1/sql-query/")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"sql\": \"<string>\",\n \"mode\": \"csv\",\n \"mode_options\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nekt.ai/api/v1/sql-query/")
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\": \"<string>\",\n \"mode\": \"csv\",\n \"mode_options\": {}\n}"
response = http.request(request)
puts response.read_body{
"state": "SUCCEEDED",
"presigned_urls": [
"https://storage.googleapis.com/bucket/query-20251119-154427-123456-000000000000.parquet?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=..."
],
"data_scanned_in_bytes": 11250,
"execution_time_in_millis": 408
}Authorizations
API Key authentication. Format: 'x-api-key: api_key'
Body
A SQL statement to run against your lakehouse, and how to return the results.
SQL query string to execute using standard SQL syntax (AWS Athena or GCP BigQuery depending on your organization's cloud provider)
Output format for query results. Options: 'csv' (default, universal compatibility) or 'parquet' (better compression and performance, recommended for large datasets)
csv- csvparquet- parquet
csv, parquet Additional options for the output format. Available options depend on your organization's cloud provider and selected mode:
AWS Organizations:
- CSV mode: No options supported (AWS Athena limitation)
- Parquet mode: 'compression' - Compression algorithm (default: 'SNAPPY', options: 'SNAPPY', 'GZIP', 'NONE')
GCP Organizations:
- CSV mode: 'delimiter' (default: ','), 'header' (default: true), 'compression' (optional: 'GZIP')
- Parquet mode: 'compression' - Compression algorithm (default: 'SNAPPY', options: 'SNAPPY', 'GZIP', 'NONE')
Example: {'compression': 'SNAPPY'} or {'delimiter': ';', 'header': true, 'compression': 'GZIP'}
Show child attributes
Show child attributes
Response
The outcome of a SQL execution: its state, where to download results, and what it scanned.
Query execution state
SUCCEEDED- SUCCEEDEDFAILED- FAILEDCANCELLED- CANCELLEDRUNNING- RUNNING
SUCCEEDED, FAILED, CANCELLED, RUNNING List of presigned URLs to download result files (1 hour expiration)
Amount of data scanned by the query (if succeeded)
Query execution time in milliseconds (if succeeded)
Error message (if failed)
Was this page helpful?