---
title: "Get a report’s metadata"
method: GET
path: "/queries/{id}/report"
tags: ["Reports"]
---

# Get a report’s metadata

`GET /queries/{id}/report`

## Request

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

Everything needed to present a saved query as a form: title, description, which connection and database the numbers come from, the variables to fill in, and the chart configuration. Never returns the SQL, so this is the endpoint to use when a caller should be able to run a query without reading it. Scoped to the caller’s company and to their own or shared queries; anything else is a 404 rather than a 403, so the endpoint cannot be used to discover query ids. Available to API keys with the `read` scope.

## Path parameters

- `id` string, cuid, required

## Response `200`

Report metadata

- ReportMeta: What the report page needs to render a saved query as a form. Deliberately excludes the SQL: the report page is the one place a query is not meant to be read as SQL, so this is strictly less than GET /queries/{id}.
  - `id` string
  - `title` string
  - `description` string, nullable
  - `connection` object, nullable: Where the numbers come from. Null when the query has no connection, in which case it cannot be run.
    - `name` string
    - `database` string
  - `variables` QueryVariable[]: The filters a reader fills in. Supply values to POST /queries/{id}/run.
    - `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.
  - `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.

## Other responses

- `401`: Bad or missing credentials
- `403`: Insufficient scope
- `404`: Query not found, or not shared with the caller

---

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