NAnace
tools

run_sql

Changed on

Run one caller-authored read-only SELECT over the workspace's tables.

Cost class: fast. No planner and no answering agent — the statement runs directly in the guarded SQL engine, against every queryable tab in the workspace registered as a view under the table_name that file-metadata and the folder-metadata table census publish. Joins across files are ordinary SQL joins; earlier run-sql results are registered too, so a returned res_… handle can be joined, aggregated, or paged with LIMIT/OFFSET in the next statement.

The full result is retained as parquet whatever the preview shows — result_citation.result_file.download_url fetches it whole. A statement that is not a read, or reads an unregistered table, is refused with invalid_request naming the rule broken and the registered tables. For a natural-language question — or when the answer should be composed and cited for you — use query-tables instead.

post/v1/workspaces/{workspace_id}/tools/run-sql

Request

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

Idempotency-Keystring nullable

Use the same key to recover an earlier request. A replay returned as a Job carries Idempotent-Replayed: true and replayed: true without a new charge; Job credits keeps the original cost. Re-serving a settled inline tool answer reports zero credits for that call and also carries Idempotent-Replayed: true; a fresh re-execution after a transient failure carries no header. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

sqlstring required

One read-only SELECT (DuckDB dialect) over the registered tables and earlier res_… handles.

Response

Successful Response

creditsinteger nullable

Credits billed for this call; zero for a free answer or replay, null when a billing receipt is unavailable.

duplicateboolean
job_idstring uuid nullable

The external operation job; absent for commands inside a search job.

result_materialization_errorstring nullable
source_pathsstring[]

The uploaded files the statement read — carried on the response itself so source attribution survives when no result file is materialized (job-attributed agent statements).

sqlstring required

The normalized statement that ran — the result's provenance.

waiver'repeat_of_job' | 'no_job' nullable

Why this call is free: repeat_of_job reuses an earlier answer; no_job answers without creating a job.

Changes

  • d002a3589a67Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status