Skip to main content

Export SQL Statement Results

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

Run a SQL statement and export its results.

Required scope: reports:write

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

  • csv: returned as a file download (text/csv), up to 100,000 rows, with a longer time limit than previews.
  • xlsx / pdf: returned as JSON with a base64 content field, up to 10,000 rows.

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.

Body:

  • sql (string, required, max 20000): the statement
  • format (string, required): csv, xlsx or pdf
  • name (string, optional, max 255): file name prefix

Request​

Responses​

OK

Response Headers
    Content-Type