---
title: "Run a saved query"
method: POST
path: "/queries/{id}/run"
tags: ["Queries"]
---

# Run a saved query

`POST /queries/{id}/run`

## Request

- Base URL: `https://saturnsql.com/api`
- URL: `https://saturnsql.com/api/queries/{id}/run`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Runs a saved query, substituting its declared `{{variables}}` from the values supplied. The caller sends values, never SQL: the SQL comes from the stored query and every value is type-checked and escaped server side. A value that is missing or invalid returns `422` with one entry per bad variable and executes nothing. An absent name falls back to that variable's default; a name present with an empty string stays empty. Same read-only guard, rate limit and monthly quota as POST /queries/execute. Available to API keys with the `execute` scope.

## Path parameters

- `id` string, cuid, required

## Query parameters

- `values` object, required
- `timeZone` string, required
- `limit` number, required
- `refresh` boolean, required

## Request body

- object
  - `values` object: Variable values by name
  - `timeZone` string: IANA zone used to resolve relative date defaults (default UTC)
  - `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 request, no connection on the query, or variables on a DynamoDB connection
- `401`: Bad or missing credentials
- `403`: Insufficient scope, paused connection, or non-read-only SQL
- `404`: Query not found
- `422`: One or more variable values are missing or invalid; nothing was executed
- `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)