> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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/{id}. Use GET /query/schema to discover the queryable tables and per-collection fields. ## OpenAPI ````yaml POST /query openapi: 3.0.0 info: title: Cloudglue API description: API for Cloudglue license: name: Apache License 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 0.7.15 servers: - url: https://api.cloudglue.dev/v1 security: - bearerAuth: [] paths: /query: post: tags: - Query summary: Run a structured query description: >- 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/{id}. Use GET /query/schema to discover the queryable tables and per-collection fields. operationId: runQuery requestBody: description: Query execution parameters content: application/json: schema: $ref: '#/components/schemas/RunQueryRequest' required: true responses: '200': description: Query executed successfully content: application/json: schema: $ref: '#/components/schemas/QueryResult' '400': description: >- Invalid request parameters or rejected SQL (multiple statements, a non-SELECT statement, SQL that could not be parsed, or a face-analysis collection in scope) content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Insufficient credit balance content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: One or more collections not found content: application/json: schema: $ref: '#/components/schemas/Error' '408': description: Query exceeded the execution time limit content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The selected collections exceed the maximum queryable dataset size content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- A natural-language query could not be compiled into valid SQL — refine the question or send sql directly content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Too many concurrent queries, or the per-minute rate limit was exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: An unexpected error occurred on the server content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RunQueryRequest: type: object required: - collections properties: collections: type: array items: type: string format: uuid minItems: 1 maxItems: 20 description: >- Collection IDs to query over. All collections must belong to your account; face-analysis collections are not supported. sql: type: string minLength: 1 maxLength: 20000 description: >- A single read-only SQL SELECT statement over the virtual tables (files, entities, segment_entities). Exactly one of sql or query must be provided. query: type: string minLength: 1 maxLength: 2000 description: >- 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. format: type: string enum: - json - csv - jsonl default: json description: >- Result format. 'json' returns rows inline (synchronous). 'csv' and 'jsonl' are for background exports only and require background: true. max_rows: type: integer minimum: 1 maximum: 10000 default: 1000 description: >- 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. background: type: boolean default: false description: >- 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: type: boolean default: false description: >- 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. QueryResult: type: object properties: id: type: string format: uuid description: Query result ID object: type: string enum: - query_result description: Object type identifier status: type: string enum: - completed - failed - in_progress - cancelled description: >- Current status of the query. Synchronous queries return 'completed' or 'failed'. created_at: type: number description: Unix timestamp of when the query was created collections: type: array items: type: string format: uuid description: Collection IDs the query ran over sql: type: string nullable: true description: The effective SQL that was executed (echoes the request's sql) columns: type: array nullable: true items: type: object properties: name: type: string description: Column name type: type: string description: SQL type of the column description: Result columns in select order rows: type: array nullable: true items: type: object additionalProperties: true description: Result rows as objects keyed by column name row_count: type: integer description: Number of rows returned truncated: type: boolean description: >- Whether the result was truncated by max_rows or the stored-result size cap dry_run: type: boolean description: >- True when the query was only validated/compiled (dry_run request): columns holds the output schema and rows is null. usage: $ref: '#/components/schemas/QueryUsage' nullable: true description: Dataset and timing usage for the run error: type: object nullable: true properties: code: type: string message: type: string description: Error details if the query failed format: type: string nullable: true enum: - json - csv - jsonl description: The result format ('csv'/'jsonl' for background exports) download_url: type: string nullable: true description: >- 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: type: number nullable: true description: Unix timestamp (ms) when download_url expires output_bytes: type: integer nullable: true description: Compressed size of a completed background export, in bytes Error: required: - error type: object properties: error: type: string QueryUsage: type: object properties: files_scanned: type: integer description: Number of files loaded into the files virtual table entity_rows: type: integer description: Number of rows loaded into the entities virtual table segment_entity_rows: type: integer description: Number of rows loaded into the segment_entities virtual table engine_ms: type: number description: SQL execution time in milliseconds total_ms: type: number description: Total processing time in milliseconds, including dataset preparation securitySchemes: bearerAuth: type: http scheme: bearer ````