Skip to main content
POST
Run a structured query

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Query execution parameters

collections
string<uuid>[]
required

Collection IDs to query over. All collections must belong to your account; face-analysis collections are not supported.

Required array length: 1 - 20 elements
sql
string

A single read-only SQL SELECT statement over the virtual tables (files, entities, segment_entities). Exactly one of sql or query must be provided.

Required string length: 1 - 20000
query
string

A natural-language question to run instead of sql. Cloudglue compiles it to SQL against the same virtual schema, runs it, and returns the compiled statement in the response's sql field. Exactly one of sql or query must be provided. Costs 4 credits (refunded if compilation fails); returns 422 if it cannot be compiled.

Required string length: 1 - 2000
format
enum<string>
default:json

Result format. 'json' returns rows inline (synchronous). 'csv' and 'jsonl' are for background exports only and require background: true.

Available options:
json,
csv,
jsonl
max_rows
integer
default:1000

Maximum number of result rows to return inline. Results with more rows are truncated (truncated: true). Does not apply to background exports, which stream the full result.

Required range: 1 <= x <= 10000
background
boolean
default:false

When true, run the query as a background export: the full result streams to a gzipped csv/jsonl file and the response returns immediately with status 'in_progress' and an id to poll. Requires format 'csv' or 'jsonl'. Reserves 4 credits, reconciled to +1 per 100MB of compressed output. Cannot be combined with dry_run.

dry_run
boolean
default:false

When true, validate (and, for a natural-language query, compile) the statement and return the effective SQL plus its output column schema without executing it over any data. No rows are produced and it is billed at a reduced rate. Cannot be combined with background.

Response

Query executed successfully

id
string<uuid>

Query result ID

object
enum<string>

Object type identifier

Available options:
query_result
status
enum<string>

Current status of the query. Synchronous queries return 'completed' or 'failed'.

Available options:
completed,
failed,
in_progress,
cancelled
created_at
number

Unix timestamp of when the query was created

collections
string<uuid>[]

Collection IDs the query ran over

sql
string | null

The effective SQL that was executed (echoes the request's sql)

columns
object[] | null

Result columns in select order

rows
object[] | null

Result rows as objects keyed by column name

row_count
integer

Number of rows returned

truncated
boolean

Whether the result was truncated by max_rows or the stored-result size cap

dry_run
boolean

True when the query was only validated/compiled (dry_run request): columns holds the output schema and rows is null.

usage
object | null

Dataset and timing usage for the run

error
object | null

Error details if the query failed

format
enum<string> | null

The result format ('csv'/'jsonl' for background exports)

Available options:
json,
csv,
jsonl
download_url
string | null

Signed URL to download a completed background export. Valid for 24 hours and not refreshed on read (re-run the export if it expires); null for synchronous runs and until a background export completes

download_expires_at
number | null

Unix timestamp (ms) when download_url expires

output_bytes
integer | null

Compressed size of a completed background export, in bytes