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": "SELECT * FROM \"nekt_raw\".\"customers\" LIMIT 100"
}
'

{
  "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
}

Endpoints

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 only
parquet: 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
}

POST

api

sql-query

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": "SELECT * FROM \"nekt_raw\".\"customers\" LIMIT 100"
}
'

{
  "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
}

Security: Your data never transits through Nekt servers. Results are stored in your organization’s cloud storage and accessed via time-limited presigned URLs (1 hour expiration).

Authorizations

x-api-key

string

header

required

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

string

required

SQL query string to execute using standard SQL syntax (AWS Athena or GCP BigQuery depending on your organization's cloud provider)

mode

enum<string>

default:csv

Output format for query results. Options: 'csv' (default, universal compatibility) or 'parquet' (better compression and performance, recommended for large datasets)

csv - csv
parquet - parquet

Available options:

csv,

parquet

mode_options

object

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

Response

200 - application/json

The outcome of a SQL execution: its state, where to download results, and what it scanned.

state

enum<string>

required

Query execution state

SUCCEEDED - SUCCEEDED
FAILED - FAILED
CANCELLED - CANCELLED
RUNNING - RUNNING

Available options:

SUCCEEDED,

FAILED,

CANCELLED,

RUNNING

presigned_urls

string<uri>[]

List of presigned URLs to download result files (1 hour expiration)

data_scanned_in_bytes

integer

Amount of data scanned by the query (if succeeded)

execution_time_in_millis

integer

Query execution time in milliseconds (if succeeded)

state_change_reason

string

Error message (if failed)