NaceDocs
DashboardGet an API key
DocumentationAPI ReferenceSDKsCLI

Workspaces

Run a SQL query

Other errors (500, 502, 503, 504) are on Errors.

POST
/v1/workspaces/{id}/tools/run-sql

Other errors (500, 502, 503, 504) are on Errors.

Authorization

bearerAuth
AuthorizationBearer <token>

Your API key, sent as Authorization: Bearer nace_sk_...

  • Where: the dashboard's API Keys page. It is shown once, when you create it.
  • Format: nace_sk_ followed by 43 URL-safe characters (A-Z, a-z, 0-9, _ and -).
  • Limit: an account can hold at most 3 active keys.
  • Wrong or missing key: returns 401 authentication_error.

In: header

Path Parameters

idstringrequired

The workspace's workspace_id.

Header Parameters

Idempotency-Keystring

Up to 200 characters, unique per account. A call that timed out keeps running: send it again with the same key and body to get its answer instead of running it twice.

Lengthlength <= 200

Request Body

application/json

sqlstringrequired

One read-only SELECT (DuckDB dialect) over the workspace's tables and earlier res_… results.

Length1 <= length <= 4096

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/workspaces/string/tools/run-sql" \  -H "Content-Type: application/json" \  -d '{    "sql": "SELECT region, SUM(amount) AS total FROM sales_2024 GROUP BY region ORDER BY total DESC"  }'
{  "sql": "string",  "duplicate": false,  "result": {    "handle": "string",    "row_count": 0,    "columns": [      {        "name": "string",        "data_type": "string"      }    ],    "rows": [      {}    ],    "preview_truncated": false,    "path": "string"  },  "source_paths": [    "string"  ],  "result_citation": {    "result_file": {      "file_id": "string",      "handle": "string",      "path": "string",      "file_name": "string",      "format": "parquet",      "row_count": 0,      "download_url": "string",      "preview_url": "string",      "download_url_expires_at": "2019-08-24T14:15:22Z"    },    "source_paths": [      "string"    ],    "sql": "string",    "grounding": {}  },  "result_materialization_error": "string",  "job_id": "string"}

Read a file POST

The text of one ingested file: all of it, one tab or section (component), some pages (pages), or a span of lines of that text (line_start, line_end), up to max_chars characters.

Describe a folder POST

Describes one folder of the workspace without reading its files: how many files it holds (or its whole subtree, recursive), their counts per category and ingestion status, its subfolders, and one page of its files' paths.