---
title: "Execute SQL"
method: POST
path: "/queries/execute"
tags: ["Queries"]
---

# Execute SQL

`POST /queries/execute`

## Request

- Base URL: `https://saturnsql.com/api`
- URL: `https://saturnsql.com/api/queries/execute`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Runs SQL against a connection and returns rows plus column metadata. Read-only guarded: only SELECT, WITH (CTE) and EXPLAIN are accepted, one statement at a time; write/DDL/admin verbs (INSERT, UPDATE, DELETE, DROP, …) are rejected with `403`, and invalid SQL with `400`. `limit` defaults to 1000, caps at 10000. Available to API keys with the `execute` scope. Exceeding the monthly query quota or the rate limit returns `429`.

## Query parameters

- `connectionId` string, required
- `sql` string, required
- `limit` number, required
- `variables` object, required
- `values` object, required
- `timeZone` string, required

## Request body

- object
  - `connectionId` string, required
  - `sql` string, required: Read-only SQL: SELECT / WITH / EXPLAIN
  - `limit` integer: Max rows (default 1000)

## Response `200`

Result rows

- QueryResult
  - `success` boolean
  - `result` object
    - `rows` object[]
    - `fields` object[]: Column descriptors. `name` and `dataTypeID` are always present; the driver may include additional fields (e.g. dataTypeSize, format, tableID) which are safe to ignore.
      - `name` string
      - `dataTypeID` integer
    - `rowCount` integer
    - `command` string
    - `duration` integer: Execution time in ms
    - `truncated` boolean: True when rows/cells were capped to fit the memory budget.

## Other responses

- `400`: Invalid SQL or non-read-only statement
- `401`: Bad or missing credentials
- `403`: Insufficient scope
- `429`: Query quota or rate limit exceeded

---

[API](https://skmtc.dev/saturnsql/apis/saturnsql-api.md) · [All operations](https://skmtc.dev/saturnsql/apis/saturnsql-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saturnsql/apis/saturnsql-api/revisions/90a3e54ad115?raw)