---
title: "Render a chart using workbook data"
method: POST
path: "/v1/workbooks/{id}/chart"
tags: ["workbooks"]
---

# Render a chart using workbook data

`POST /v1/workbooks/{id}/chart`

## Path parameters

- `id` string, required

## Request body

- ChartRequest — Options for rendering a chart from workbook data.
  - `apply` DataTransformation[], nullable — Cells to update before rendering the chart.
    - `target` union, required — Reference for the cell to write to
      - string — A1-style string reference with optional sheet prefix
      - ReferenceObject — A reference to a range of spreadsheet cells.
        - `cells` string, required — Unprefixed A1-style range, id, or name
        - `sheet` string, nullable, required — Name of the sheet to reference
    - `value` union, required — Value to write to the target cell
      - integer
      - number
      - string
      - boolean
  - `chart` ChartRenderOptions, required — Options for rendering a chart from workbook data. Specify the data range, chart type, image output format, and title and axis labels.
    - `data` string, nullable — Chart data range, prefixed with an equals sign
    - `dataLines` string, nullable — Chart data range, prefixed with an equals sign, used for lines in a combo chart
    - `type` 'area' | 'bar' | 'column' | 'combo' | 'line' | 'pie' | 'scatterplot' | 'waterfall' — Types of charts that can be rendered using workbook data.
    - `format` 'png' | 'svg' — Supported image types for rendering charts from workbook data.
    - `numberFormat` string, nullable — Number format pattern used for formatting labels on the chart.
    - `values` 'none' | 'selective' | 'all' — Options for labelling individual data values on a chart. If "none" (the default) then no data labels are shown. If "selective", data labels are shown when they fit without overlap. If "all", all values are labelled.
    - `labels` string, nullable — Range of cells to use as the chart's x-axis labels, prefixed with an equals sign
    - `legend` string, nullable — Range of cells to use as the chart's legend labels, prefixed with an equals sign
    - `legendLines` string, nullable — Range of cells to use as the chart's line labels in the legend, prefixed with an equals sign
    - `title` string, nullable — Cell reference to use as the chart's title. Can also be plain text.
    - `subtitle` string, nullable — Cell reference to use as the chart's subtitle. Can also be plain text.
    - `footnote` string, nullable — Cell reference to use as the chart's footnote text. Can also be plain text.
    - `colorByPoint` string, nullable — Vary colors by point rather than series.
    - `dir` '' | 'col' | 'row' — Enum representing the supported read orientations for data directions.
    - `stacked` 'false' | 'true'
    - `legendVisible` 'false' | 'true'
    - `blanks` 'gap' | 'zero' | 'span' — Enum representing the supported strategies for handling blank or missing data points.
    - `interpolate` 'linear' | 'step' | 'step-after' | 'step-before' | 'monotone' | 'basis' — Enum representing the supported interpolation types for data visualization or curve fitting.
    - `chartColors` string, nullable — An Excel array expression that returns a 1-dimensional list of HTML color strings
    - `sortBy` integer, nullable — The number of which series the data should be sorted by (e.g. 1 for the first series).
    - `sortOrder` '' | 'ascending' | 'descending'
    - `axisValue` ValueAxisOptions — How an axis representing value magnitudes is presented.
      - `title` string, nullable — Cell reference to use as the axis title. Can also be plain text.
      - `type` 'linear' | 'log' — Types of scales that can be used by an axis.
      - `numberFormat` string, nullable — Number format pattern used for formatting the axis labels.
      - `reverse` 'false' | 'true'
      - `min` number, nullable — A minimum value for the axis.
      - `max` number, nullable — A maximum value for the axis.
      - `clip` 'false' | 'true'
    - `axisDim` DimAxisOptions — How an axis representing dimensional categories is presented.
      - `title` string, nullable — Cell reference to use as the axis title. Can also be plain text.
      - `numberFormat` string, nullable — Number format pattern used for formatting the axis labels.
      - `reverse` 'false' | 'true'
  - `width` integer, nullable — Width of the chart image in pixels. If not given, a width of 764px is used. A chart's height cannot be set explicitly because it will differ depending upon chart type, title, legend, axis labels, and so on.
  - `matte` string, nullable — Hex color code for the chart's background matte, e.g. '#FFFFFF' for white, if not specified, the chart will have a transparent background. Note, this is currently only supported for PNG images.

## Response `200`

Chart rendered as an image

## Other responses

- `400` — Error returned when you make a bad request
- `403` — Error returned when you don't have permission to query a workbook
- `429` — Error returned when you exceed your API rate limit

---

[API](https://skmtc.net/grid-is/apis/grid-api.md) · [All operations](https://skmtc.net/grid-is/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grid-is/grid-api/versions/2f55490ab23d/schema)