---
title: "Set a report’s chart, or clear it"
method: PUT
path: "/queries/{id}/chart"
tags: ["Reports"]
---

# Set a report’s chart, or clear it

`PUT /queries/{id}/chart`

## Request

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

Stores a ChartSpec on a saved query, or clears it with `null` to go back to deciding from the result shape. The spec is stored verbatim and not validated against columns, because the columns only exist after a run; a spec that stops fitting falls back to the guess at render time rather than erroring. Owner only, and its own route rather than a field on PUT /queries so that choosing a chart cannot collide with that endpoint’s optimistic-concurrency baseline. Session token only; API keys cannot reach this.

## Path parameters

- `id` string, cuid, required

## Request body

- object
  - `chart` ChartSpec, required: 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.

## Response `200`

The stored configuration

- object
  - `success` boolean
  - `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

- `400`: Chart must be an object or null
- `401`: Bad or missing credentials
- `403`: Editor access required
- `404`: Query not found, or the caller does not own it

---

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