Run Structured Query
Run a synchronous read-only SQL query over the structured data extracted from one or more collections. Queries execute against three virtual tables — files, entities, and segment_entities — built from each file’s most recent completed extraction.
Each query costs 2 credits. Results are returned inline and stored, so completed runs can be re-fetched via GET /query/. Use GET /query/schema to discover the queryable tables and per-collection fields.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Query execution parameters
Collection IDs to query over. All collections must belong to your account; face-analysis collections are not supported.
1 - 20 elementsA single read-only SQL SELECT statement over the virtual tables (files, entities, segment_entities). Exactly one of sql or query must be provided.
1 - 20000A 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.
1 - 2000Result format. 'json' returns rows inline (synchronous). 'csv' and 'jsonl' are for background exports only and require background: true.
json, csv, jsonl 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.
1 <= x <= 10000When 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.
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
Query result ID
Object type identifier
query_result Current status of the query. Synchronous queries return 'completed' or 'failed'.
completed, failed, in_progress, cancelled Unix timestamp of when the query was created
Collection IDs the query ran over
The effective SQL that was executed (echoes the request's sql)
Result columns in select order
Result rows as objects keyed by column name
Number of rows returned
Whether the result was truncated by max_rows or the stored-result size cap
True when the query was only validated/compiled (dry_run request): columns holds the output schema and rows is null.
Dataset and timing usage for the run
Error details if the query failed
The result format ('csv'/'jsonl' for background exports)
json, csv, jsonl 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
Unix timestamp (ms) when download_url expires
Compressed size of a completed background export, in bytes