Skip to main content

Validate SQL Statement

POST 
/api/v2/report-builder/sql/validate

Check a SQL statement without running it. Returns whether it is valid, any errors (which block running) and warnings (which do not, e.g. a missing LIMIT), the allowlisted tables it reads, and the database's estimate of rows it will scan.

Required scope: reports:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Every statement passes the same safeguards: it must be a single read-only SELECT (CTEs, UNIONs, subqueries and window functions are supported); every table it reads must be on the SQL-reports allowlist (see Get SQL Schema); schema-qualified references, variables, placeholders, locking clauses, SELECT ... INTO, stored routines and a small set of unsafe functions (SLEEP, BENCHMARK, LOAD_FILE, GET_LOCK, sequence functions, ...) and server-information functions (DATABASE(), USER(), CURRENT_USER, VERSION(), CONNECTION_ID(), ...) are rejected. A few columns that hold access tokens (purchase_orders.share_token, purchase_invoices.share_token) can never be read: naming them anywhere is rejected, and so is SELECT * / alias.* on a table that has one — list the columns you need instead. Statements run in a read-only transaction with a per-statement time limit and a row cap, and every execution is recorded in an audit log.

Requires the reports.sql permission (administrators always have it). Personal access tokens need the reports:write scope (reports:read is enough for Get SQL Schema). Users without the permission receive 403.

Rate limited to 120 requests per minute per user.

Body:

  • sql (string, required, max 20000): the statement

Request​

Responses​

OK

Response Headers
    Content-Type