---
title: "Get a saved query"
method: GET
path: "/queries/{id}"
tags: ["Queries"]
---

# Get a saved query

`GET /queries/{id}`

## Request

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

Returns a single saved query by id. Available to API keys with the `read` scope.

## Path parameters

- `id` string, cuid, required

## Response `200`

Saved query

- SavedQuery
  - `id` string
  - `name` string
  - `sql` string
  - `connectionId` string, nullable
  - `folderPath` string, nullable: A single flat folder label (not a nested path); "A/B" is one folder named "A/B", not "A" containing "B". null = root.
  - `isShared` boolean
  - `description` string, nullable: Subtitle on the report page. Returned by GET /queries; nothing can set it yet, so always null.
  - `chart` ChartSpec: How a report should be drawn. Stored verbatim and interpreted at render time, since the columns a spec refers to only exist after a run: a spec naming a column the SELECT list no longer returns falls back to the shape-derived guess rather than failing. With no spec stored, the result shape decides — see the "saved query is also a report page" section of the API guide for the rules an agent should write SQL against.
    - `type` 'line' | 'area' | 'bar' | 'scatter' | 'share' | 'number' | 'none', required: `none` suppresses the chart for good, which is why it is distinct from a null `chart`. `share` is never guessed and must be set explicitly: its shape is identical to `bar` and nothing in the data says which is meant.
    - `x` string: Column for the x axis or the category. Absent for `number`.
    - `series` string[]: Measure columns, in order. Capped at 3: the validated palette separates three series by lightness and a fourth has no colour.
    - `group` string: Low-cardinality column splitting a scatter into groups.
  - `userId` string
  - `variables` QueryVariable[]: Declared `{{name}}` variables, in first-appearance order in the SQL. Empty when the query has none.
    - `name` string, required: Matches `[A-Za-z_][A-Za-z0-9_]*`
    - `type` 'date' | 'text' | 'number' | 'boolean' | 'dropdown', required
    - `required` boolean: An empty value for a required variable is a 422, not an empty substitution.
    - `default` object, nullable: Used when the value is absent. A `relative` default is only valid on a `date` variable and resolves against the caller time zone (or the schedule time zone).
      - `kind` 'fixed' | 'relative'
      - `value` string: Literal for `fixed`; one of today, yesterday, 7_days_ago, 30_days_ago, 90_days_ago, start_of_this_month, start_of_last_month, end_of_last_month, start_of_this_year for `relative`.
    - `options` string[]: Dropdown only, non-empty. A value outside this list is a 422.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `401`: Bad or missing credentials
- `404`: Query not found

---

[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)